mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 06:53:15 +00:00
651dff5dd3
Adds three handbook pages covering conventions that were previously scattered across feedback memories or rederived from scratch each time: - bedrock.md captures the cross-region inference profile requirement for Claude 4.x Bedrock Agents and the alias-version pinning gotcha, plus the IAM resource pattern and the KB Docker requirement. - dev-environment.md documents the workstation directory layout, pyenv/Node conventions, the macOS launchd/TCC sandbox gotcha, and cleanup cadence. - lambda-template.md provides a minimal SAM scaffold that follows the Lambda defaults already in aws-infrastructure.md (Python 3.12, arm64, explicit 60-day log retention, scoped Secrets Manager access, module-level secret cache). Also extends two existing pages: - sam-project-layout.md gains a Lambda Layers section with the BuildMethod nesting pattern that caused a ~22-hour production outage when violated. - naming-conventions.md adds a Legacy Stacks note acknowledging that pre-convention PascalCase stacks (SeaHavenDoorUnlockStack, WorkorderIngestStack) stay as-is rather than risk stack replacement.
1.8 KiB
1.8 KiB
Engineering Handbook
Engineering conventions and best practices for Sea Haven Industries.
Contents
- Naming Conventions -- kebab-case everywhere, no exceptions
- Development Environment -- workstation directory layout, pyenv, Node, launchd/TCC
- Git Workflow -- feature branches, incremental commits, deploy-then-merge
- Commit Messages -- imperative mood, 50/72 rule, explain "why"
- Pull Requests -- scope, title, description format, merge strategy
- Code Review -- what to look for, giving feedback, turnaround expectations
- GitHub Standards -- branch defaults, repo hygiene, Dependabot
- AWS Infrastructure -- SAM vs CDK, Lambda defaults, CloudFormation
- SAM Project Layout -- standard directory structure for serverless projects
- Lambda Starter Template -- minimal SAM scaffold for a new Python Lambda
- Secrets and Configuration -- Secrets Manager vs SSM Parameter Store
- CI/CD Pipelines -- every deployable repo gets a pipeline, no manual deploys
- Bedrock -- cross-region inference profiles, alias pinning, KB Docker requirement
- Git Hooks -- recommended pre-push and pre-commit hooks
- Scripts -- repo provisioning, automation tooling
- CDK Constructs -- shared VPN EC2 instance construct and other reusable patterns
Contributing
See CONTRIBUTING.md.
License
This work is licensed under CC-BY-4.0. The commit messages section adapts content from commit-messages-guide by Romulo Oliveira, also licensed under CC-BY-4.0.