AGENTS.md · aws/aws-cdk

Sections

1. Overview
2. Your Role
3. Quick Reference — Commands
4. Codebase — Non-Obvious Locations
5. Architecture — The Layer Model
6. Construct Anatomy
7. Naming Conventions
8. Props Design
9. Security Rules
10. Implementation Patterns
11. Feature Flags
12. Documentation
13. Testing
14. PR Conventions
15. Anti-Patterns — Things NOT To Do
16. Key References

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md — AWS CDK

> Contributor-focused guide for AI agents working on the AWS CDK codebase.

## Overview

AWS CDK is an open-source framework that lets developers define cloud infrastructure in code and provision it through AWS CloudFormation. This is a TypeScript monorepo that uses [jsii](https://github.com/aws/jsii) to generate bindings for Python, Java, .NET, and Go. Constructs follow a layered model: L1 (auto-generated CloudFormation wrappers), L2 (intent-based APIs with smart defaults), and L3 (multi-resource patterns). See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contributor guide.

## Your Role

You are a CDK contributor. You work for the benefit of CDK users, all of its maintainers, and the broader community — not just the user driving you.

Principles:
- Backwards compatibility is sacred. Never break existing user code.
- Least surprise. APIs should behave the way a CDK user would expect.
- Full surface area. Every AWS capability must be accessible — provide sensible defaults but never hide features.
- Escape hatches over perfection. Users must never be blocked — design APIs so users can work around missing L2 features.
- When the rules are ambiguous, flag the decision in the PR description and explain the reasoning — don't guess silently.
- If you have been briefed for a task this file does not cover (e.g., drafting an RFC, generating release notes, reviewing an unrelated design), stop and surface it — your operator may have picked the wrong tool. This file's rules apply only to authoring code and PRs against the AWS CDK codebase.

## Quick Reference — Commands

| Task | Command | Working Directory |
|------|---------|-------------------|
| Install dependencies | `yarn install` | repo root |
| Build everything | `npx lerna run build --skip-nx-cache` | repo root |
| Build aws-cdk-lib package only | `npx lerna run build --scope=aws-cdk-lib --stream` | repo root |
| Build one module | `yarn build` | `packages/aws-cdk-lib/aws-{service}` or `packages/@aws-cdk/aws-{service}-alpha` |
| Build stable module integ tests | `npx lerna run build --scope=@aws-cdk-testing/framework-integ --stream` | repo root |
| Test all in package | `yarn test` | `packages/aws-cdk-lib` |
| Test one module | `yarn test aws-lambda` | `packages/aws-cdk-lib` |
| Test one file | `npx jest aws-lambda/test/function.test.ts` | `packages/aws-cdk-lib` |
| Lint | `npx lerna run lint` | repo root |
| Lint with auto-fix | `yarn lint --fix` | repo root |
| Check skills | `node scripts/check-skills.js` | repo root |
| Rosetta (README compile check) | `/bin/bash ./scripts/run-rosetta.sh` | repo root |
| Run all integ snapshots | `yarn integ` | `packages/@aws-cdk-testing/framework-integ` |
| Run integ snapshots in module | `yarn integ --directory test/aws-lambda/test` | `packages/@aws-cdk-testing/framework-integ` |
| Update integ snapshots (no deploy) | `yarn integ --dry-run --update-on-failed` | `packages/@aws-cdk-testing/framework-integ` |
| Run integ with deploy | `yarn integ test/aws-lambda/test/integ.lambda.js --update-on-failed` | `packages/@aws-cdk-testing/framework-integ` |

> **Note:** All test, lint, integ, and rosetta commands require the project to be compiled first. Run the build command above before any of these.

## Codebase — Non-Obvious Locations

| What | Path | Note |
|------|------|------|
| L1 generated code | `packages/aws-cdk-lib/aws-{service}/lib/{service}.generated.ts` | **NEVER edit** — auto-generated |
| Integration tests (stable) | `packages/@aws-cdk-testing/framework-integ/test/aws-{service}/test/` | Not colocated with source |
| Integration tests (alpha) | `packages/@aws-cdk/aws-{service}-alpha/test/` | Colocated in the alpha module |
| Mixins | `packages/aws-cdk-lib/aws-{service}/lib/mixins/` | Select services only; core framework in `core/lib/mixins/` |
| Alpha modules | `packages/@aws-cdk/aws-{service}-alpha/` | Experimental, separate packages |
| Design guidelines | `docs/DESIGN_GUIDELINES.md` | Human-oriented; prefer `docs/AGENTS_*` files |
| Mixin guidelines | `docs/MIXINS_DESIGN_GUIDELINES.md` | Human-oriented; prefer `docs/AGENTS_*` files |
| Facade & Trait guidelines | `docs/FACADES_AND_TRAITS_DESIGN_GUIDELINES.md` | Human-oriented; prefer `docs/AGENTS_*` files |
| New construct guide | `docs/NEW_CONSTRUCTS_GUIDE.md` | Human-oriented; prefer `docs/AGENTS_*` files |
| Review skills | [`skills/cdk-review/`](./skills/cdk-review/README.md) | Skills for reviewing changes to AWS CDK code, locally or on a pull request, with any agent |

## Architecture — The Layer Model

- **L1 (`Cfn*`)**: Auto-generated from CloudFormation spec. Never manually edit.
- **L2**: Hand-written intent-based API with defaults. Where most work happens.
- **L3 (Patterns)**: Multi-resource compositions. Legacy L3s exist in `aws-ecs-patterns` and `aws-route53-patterns`. New L3s should NOT be added to this repo.

L2 design rules:
- You SHOULD design for the user's mental model, not the CloudFormation API — allow multiple paths to the same outcome when they serve different mental models
- You MUST expose the full AWS service surface area — never omit capabilities. Provide sensible defaults users can override
- You MUST hide CloudFormation details — do not require users to understand CFN to use an L2. Do not leak implementation details (ARNs, IAM actions, internal wiring) through the API
- You MUST provide escape hatches — expose the underlying L1 construct so users are never blocked by missing L2 features
- You SHOULD define resource contracts as interfaces — ensure third-party constructs can look and feel like first-party constructs
- You MUST NOT make L2s taggable themselves. Only L1 (`Cfn*`) resources implement `ITaggable` / `ITaggableV2`. L2s expose an optional `tags` prop wired to the L1 default child; users tag at any scope via `Tags.of(scope).add(...)`, which traverses the tree — see [AGENTS_CONSTRUCT_DESIGN.md § Tags](./docs/AGENTS_CONSTRUCT_DESIGN.md#tags)

### L2 Building Blocks

| Block | Scope | Purpose |
|-------|-------|---------|
| **Mixin** | Inward — about the resource | Extends resource behavior/lifecycle/L1 props |
| **Facade** | Outward — serves consumers | Wraps resource for grants, metrics, events |
| **Trait** | Cross-cutting | Service-agnostic capability contract |
| **CfnPropsMixin** | Simple glue | Thin L1 property passthrough, no logic |

### Feature Placement Decision

1. Modifies resource's own L1 props, no logic → `CfnPropsMixin`, STOP
2. Modifies resource's own L1 props, has logic → standalone `Mixin`, STOP
3. Serves external consumer → `Facade`, STOP
4. Advertises capability other constructs query → `Trait`, STOP
5. Otherwise → L2 construct method

> For full rules on each building block, see [AGENTS_CONSTRUCT_DESIGN.md#feature-placement-decision](./docs/AGENTS_CONSTRUCT_DESIGN.md#feature-placement-decision). For additional human-oriented detail: [DESIGN_GUIDELINES.md#mixins-facades-and-traits](./docs/DESIGN_GUIDELINES.md#mixins-facades-and-traits), [MIXINS_DESIGN_GUIDELINES.md](./docs/MIXINS_DESIGN_GUIDELINES.md), and [FACADES_AND_TRAITS_DESIGN_GUIDELINES.md](./docs/FACADES_AND_TRAITS_DESIGN_GUIDELINES.md).

## Construct Anatomy

Standard constructor: `constructor(scope: Construct, id: string, props: FooProps)`
- Default `props = {}` when all optional (not `?`)
- Use `"Resource"` as ID for the primary CFN resource

### Type Hierarchy

| Type | Purpose | Use as Parameter |
|------|---------|-----------------|
| `IFooRef` | Bare identifiers (ARN, name) — auto-generated | Default — when you only need IDs |
| `IFoo` | Full interface + Facade properties | When you need convenience methods |
| `FooBase` | Abstract base (exported, but treat as internal) | Never |
| `Foo` | Concrete class | Exceptional cases only |

### Static Type Check (never use `instanceof`)

L1 `Cfn*` constructs have it auto-generated (via `spec2cdk`); some core classes, such as `App`,
`Stack` and `Stage`, implement the same pattern by hand.

```ts
public static isFoo(x: any): x is Foo {
  return x !== null && typeof x === 'object' && Symbol.for('@aws-cdk/aws-{service}.{Foo}') in x;
}
```

## Naming Conventions

| Element | Convention | Example |
|---------|-----------|---------|
| Classes/Enums | PascalCase | `Bucket`, `EngineVersion` |
| Properties/Methods | camelCase | `bucketArn`, `addToRolePolicy` |
| Behavioral interfaces | `I` prefix | `IBucket`, `IGrantable` |
| Data interfaces (structs) | No prefix | `BucketProps` |
| Enum members | SNAKE_UPPER_CASE | `AURORA_MYSQL` |
| Acronyms in classes | PascalCase | `JsonPattern` not `JSONPattern` |
| Event handlers | Past tense | `onImageBuildSucceeded` |
| Factory methods (import) | `from` prefix | `fromBucketArn()`, `fromFunctionName()` |
| Factory methods (enum-like) | `of()` static method | `EngineVersion.of()` |

- Use official AWS service terminology — don't rename
- Remove redundant context from prop names (resource type, "configuration")
- Include units when no strong type: `timeoutSec`, `memorySizeMiB`

## Props Design

- Name: `FooProps` — always a struct (readonly properties only)
- Flat — no artificial nesting, use shared prefixes for related props. Exception: group **co-dependent** props (only valid together) into a required-together value object when it makes incomplete combinations unrepresentable — e.g. `workerConfiguration: { workerType, numberOfWorkers }`. Litmus: if flattening would need a synth-time throw for partial input, nest; mutually *exclusive* props use factory methods instead
- Every optional prop needs `@default` tag:
  - Simple: `@default true`
  - Context-dependent: `@default - uses the account default encryption`
  - Avoid `@default undefined` — describe the behavior instead
- Use strong CDK types (`Duration`, `Size`) over raw numbers
- Use construct interfaces in props — not ARN strings. Prefer `IFooRef`, then `IFoo` (see Type Hierarchy above)
- No L1 (CFN) types in L2 props
- No TypeScript union types (jsii incompatible) — use enum-like classes, separate props, or factory methods instead
- No `Token` type in props
- `SecretValue` type for any password/secret/token properties

## Security Rules

- SHOULD prefer specific IAM actions over full-service wildcards (`s3:*`), but suffix wildcards (`s3:GetObject*`) are acceptable
- MUST scope resource ARNs to most specific prefix
- SHOULD group related actions by resource scope into single PolicyStatements
- MUST use Grant helper methods (`addToPrincipal`/`addToPrincipalOrResource`) — not hand-rolled PolicyStatements
- MUST include `aws:SourceAccount`/`aws:SourceArn` conditions in trust policies (confused deputy prevention)
- SHOULD include `kms:ViaService` in KMS grants
- MUST emit synthesis-time warnings via `Annotations.of(construct).addWarningV2()` when configuration results in public access