mirror of
https://github.com/Sea-Haven-Industries/open-swe.git
synced 2026-09-30 12:43:16 +00:00
0fc466a06b
Some checks are pending
CI / Lint (push) Waiting to run
CI / Format check (push) Waiting to run
CI / Unit tests (push) Waiting to run
CI / Playwright E2E (push) Waiting to run
CI / Docker build smoke (push) Waiting to run
CI / Triage ledger up to date (push) Waiting to run
CI / ui bun.lock in sync (push) Waiting to run
Refs: #114 Co-authored-by: amoussa1229 <166072409+amoussa1229@users.noreply.github.com>
79 lines
2.5 KiB
Text
79 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.
|