mirror of
https://github.com/Sea-Haven-Industries/engineering-handbook.git
synced 2026-09-30 04:33:13 +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.
48 lines
1.7 KiB
Markdown
48 lines
1.7 KiB
Markdown
# Naming Conventions
|
|
|
|
## The Rule
|
|
|
|
kebab-case for everything. No exceptions.
|
|
|
|
No `snake_case`, `PascalCase`, or mixed styles anywhere.
|
|
|
|
## Where It Applies
|
|
|
|
| Resource | Example |
|
|
|---|---|
|
|
| Repository names | `expense-approval-bot`, `door-unlock-api` |
|
|
| CloudFormation stack names | `expense-approval-bot` (must match repo name) |
|
|
| Lambda function names | `expense-approval-bot-process-receipt` |
|
|
| DynamoDB table names | `expense-approval-bot-receipts` |
|
|
| S3 bucket names | `expense-approval-bot-uploads` |
|
|
| Secrets Manager secrets | `expense-approval-bot/slack-signing` |
|
|
| Feature branches | `feature/add-receipt-parser` |
|
|
|
|
## CDK Gotcha
|
|
|
|
CDK generates PascalCase stack names by default. Always set an explicit `stackName` (TypeScript) or `stack_name` (Python) in your stack definition to enforce kebab-case.
|
|
|
|
```typescript
|
|
new MyStack(app, 'MyStack', {
|
|
stackName: 'my-stack',
|
|
});
|
|
```
|
|
|
|
## Examples
|
|
|
|
| Bad | Good | Why |
|
|
|---|---|---|
|
|
| `ExpenseApprovalBot` | `expense-approval-bot` | PascalCase |
|
|
| `expense_approval_bot` | `expense-approval-bot` | snake_case |
|
|
| `expenseApprovalBot` | `expense-approval-bot` | camelCase |
|
|
| `Expense-Approval-Bot` | `expense-approval-bot` | Mixed case |
|
|
| `feature/AddParser` | `feature/add-parser` | PascalCase in branch |
|
|
|
|
## Legacy Stacks
|
|
|
|
A handful of stacks predate this convention and remain PascalCase because renaming would require stack replacement (data loss, deploy windows). Examples in active use:
|
|
|
|
- `SeaHavenDoorUnlockStack`
|
|
- `WorkorderIngestStack`
|
|
|
|
Do not rename these solely to enforce kebab-case if doing so means tearing down and recreating production resources. New stacks must follow the convention; legacy stacks may keep their names until a planned migration brings them in line.
|