# CLAUDE.md: AWS CDK v2 (TypeScript)

## Commands
- `npm run build` · `npm test` · `npx cdk synth` · `npx cdk diff <Stack>`
- **Never run `cdk deploy` or `cdk destroy` unless asked.** Show `cdk diff` output for review instead.

## Structure
- `bin/app.ts` instantiates stacks per environment with explicit `env: { account, region }`.
- `lib/stacks/*` compose `lib/constructs/*`. Reusable pieces are L3 constructs with typed props interfaces.
- Only `aws-cdk-lib` and `constructs` imports (v2). No v1 `@aws-cdk/*` packages.

## Rules
- Permissions with grant methods (`bucket.grantRead(fn)`, `table.grantReadWriteData(fn)`) instead of hand-written IAM policies. No `*` actions or resources.
- Stateful resources (S3, DynamoDB, RDS) set `removalPolicy: RemovalPolicy.RETAIN` in production and have encryption, backups/PITR, and blocked public access.
- Don't hard-code physical names unless needed; let CDK generate them.
- Changing a construct's id replaces the resource. Avoid it for stateful resources, or call out the replacement.
- Lambdas use `NodejsFunction` with a pinned runtime (`Runtime.NODEJS_22_X`), set memory/timeout, and log retention.
- Config in `cdk.json` context or typed props, not `process.env` scattered in stacks.
- Apply `cdk-nag` (`AwsSolutionsChecks`) if the project uses it and fix findings or suppress with a reason.

## Tests
`aws-cdk-lib/assertions`: `Template.fromStack` with `hasResourceProperties` for key resources; keep snapshot tests up to date only when the diff is intended.