Agent RulesAgent Rules
AW

AWS CDK

Cloud Development Kit patterns, constructs, and best practices

Amazon Web Services
Infrastructure
cdk
iac
cloudformation
constructs
Use in BuilderAll Amazon Web Services Options

Details

Language / Topic
awsAmazon Web Services
Category
Infrastructure

Rules

balanced
- Use L2 and L3 constructs over L1 (Cfn*) constructs — they provide sensible defaults and less boilerplate
- Organize stacks by lifecycle and ownership — resources that change together should be in the same stack
- Use cdk.context.json for cached values and cdk.json for project configuration; commit both to source control
- Pass references between stacks using stack outputs and cross-stack references, not hardcoded ARNs
- Run cdk diff before every deploy to review changes; never deploy without reviewing the changeset
- Use L2/L3 constructs over L1 (Cfn*) — they provide secure defaults and reduce boilerplate
- Organize stacks by lifecycle: networking stack, database stack, application stack — deploy independently
- Use cdk.context.json for cached lookups; commit it to source control for reproducible deployments
- Pass references between stacks via exports/imports, not hardcoded strings or SSM parameter lookups
- Run cdk diff before every deploy; require approval in CI/CD pipelines for production changes
- Use CDK Aspects for cross-cutting concerns: enforce tagging, encryption, or logging on all resources
- Create custom constructs for repeated patterns (e.g., StandardApiLambda, MonitoredQueue)
- Use removal policies: set RemovalPolicy.RETAIN for databases and S3 buckets, DESTROY for dev environments
- Store environment-specific config in CDK context or environment variables, not in construct code
- Use cdk-nag to scan stacks for security and compliance issues before deploying
- Write snapshot tests with assertions library to catch unintended infrastructure changes
- Keep constructs stateless — pass configuration as props, don't read from environment inside constructs