# AGENTS.md — CDK conventions

Supplement to `AGENTS.md.aws`. Merge into the repo root `AGENTS.md` alongside
the AWS base conventions.

## Directory layout

```
.
├── bin/
│   └── <app>.ts              # CDK app entrypoint
├── lib/
│   └── <stack-name>.ts       # Stack definitions
├── cdk.json                  # CDK context + config
├── cdk.context.json          # Resolved context values (git-committed)
├── package.json              # Exact-pinned CDK dependencies
├── tsconfig.json
└── Makefile                  # Synth/deploy shortcuts
```

## CDK dependencies — exact pins

```json
{
  "dependencies": {
    "aws-cdk-lib": "2.100.0",
    "constructs": "10.3.0"
  },
  "devDependencies": {
    "aws-cdk": "2.100.0",
    "typescript": "~5.4.0"
  }
}
```

- Never use `^` or `*` ranges on CDK packages. All CDK libs (`aws-cdk-lib`,
  `aws-cdk`, `constructs`, `@aws-cdk/*`) must be exact-pinned.
- When upgrading CDK, upgrade the CLI (`aws-cdk`) and the lib
  (`aws-cdk-lib`) to the same version in a single commit.

## ARM64 / QEMU build note

CDK's `Lambda` and `DockerImageFunction` constructs default to `x86_64`. When
targeting ARM64 (`Architecture.ARM_64`), note that building Docker images on
a non-ARM host requires QEMU emulation. For local development, ensure QEMU is
installed:

```bash
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
```

Agents running in the cloud sandbox may not have QEMU. When ARM64 Docker
builds fail, either switch the Lambda architecture to `X86_64` (if
compatible) or use a pre-built ARM64 image from ECR instead of building in
the sandbox.

## `overrideLogicalId` — never remove

CDK's `overrideLogicalId` method forces a deterministic physical ID for a
construct. Removing it on a resource that was previously deployed with one
**forces replacement** — CloudFormation will delete and recreate the resource.

- **Never remove an existing `overrideLogicalId` call.** If the logical ID
  must change, document why in the PR description and confirm the replacement
  impact.
- When adding a new `overrideLogicalId`, prefer stable, descriptive names
  (e.g. `MyQueueDLQ` over `ResourceABC123`).

## Build & verify

```bash
npm run build   # tsc compile
cdk synth       # Synthesize CloudFormation
cdk diff        # Show changes before deploy (do NOT deploy)
```

- Run `npm run build && npx cdk synth` before pushing. Do not commit
  `cdk.out/`.
- If the repo has a `Makefile` wrapping these, use the Makefile targets.