Skip to content

project rulesDevOps and cloudawstypescript

AWS CDK Rules

Project rules for AWS CDK in TypeScript: construct layers, stable naming, removal policies, assertion tests and a mandatory cdk diff review.

npx workspacetemplates add aws-cdk-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file20 lines · 1.4 KBFile
# Project rules: AWS CDK (TypeScript)

## Layout
- `bin/` holds the app entry, `lib/constructs/` reusable constructs, `lib/stacks/` deployable stacks, `test/` the tests. Keep stacks thin and put logic in constructs.
- Prefer L2 constructs. Drop to L1 (`Cfn*`) or escape hatches only with a comment saying what the L2 lacks.
- Pass environment as props (account, region, stage) from the app file. Never read `process.env` inside a construct and never hard-code account IDs.

## Naming and state
- Do not set physical names (`bucketName`, `tableName`) unless a cross-stack contract demands it; a fixed name blocks replacement.
- Set `removalPolicy: RETAIN` on databases, buckets and key stores in production, and enable point-in-time recovery or versioning.
- Split stateful and stateless resources into separate stacks so a code change cannot replace data.
- Tag every stack with `owner` and `stage`.

## Security
- Grant access with `grantRead`, `grantWrite` and similar methods. Write a raw IAM statement only when no grant exists, and never use `*` for both actions and resources.
- Keep secrets in Secrets Manager or SSM; reference them, do not inline values.

## Tests and delivery
- Use `Template.fromStack` with `hasResourceProperties` for key assertions, and snapshot tests sparingly.
- Run `npx tsc --noEmit`, `npm test`, `npx cdk synth` and `npx cdk diff` before finishing. Report any resource marked for replacement or deletion and wait for approval.

What it does

This file tells an agent how to organize an AWS CDK app written in TypeScript. It separates reusable constructs from stacks and keeps environment choices out of the construct code.

It also treats infrastructure changes with care: stateful resources are protected, tests assert on the synthesized template, and every deploy starts with a reviewed diff.

Example

you › Add a queue and a worker Lambda that reads from it

agent › The agent adds a QueueWorker construct, grants consume access with grantConsumeMessages, adds a dead-letter queue, writes a Template assertion test and shows the cdk diff with no replacements.

Questions

Why avoid fixed resource names?
CloudFormation cannot replace a resource whose name is fixed, so an update that needs a new resource fails. Generated names avoid that trap.
Can I use it with Python CDK?
The principles carry over, but the layout and test commands here are for TypeScript. Adjust the commands if you use another language.
  • Docker Rules

    Project rulesdocker

    Free
  • GitHub Actions Rules

    Project rulesgithub-actions

    Free
  • Kubernetes Rules

    Project ruleskubernetes

    Free
  • Serverless Lambda Rules

    Project rulesaws

    Free