mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 05:43:15 +00:00

Add Bedrock, dev-env, and Lambda template pages (#7 )

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.

2026-05-14 19:50:37 -04:00

1.7 KiB

Raw Blame History

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.

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.

1.7 KiB Raw Blame History