mirror of
https://github.com/Sea-Haven-Industries/open-swe.git
synced 2026-10-02 06:13:16 +00:00
80 lines
2.5 KiB
Text
80 lines
2.5 KiB
Text
|
# 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.
|