Home › AWS CDK › AWS CDK (TypeScript) CLAUDE.md

AWS CDK (TypeScript) CLAUDE.md

CLAUDE.md for AWS CDK v2 apps in TypeScript: constructs, least-privilege grants, snapshot tests, and safe deploys.

Claude Code (CLAUDE.md)AWS CDK

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# 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.