# AGENTS.md — AWS conventions

These rules apply to any repository that deploys to AWS (SAM, CDK, or plain
CloudFormation). Place this file at the repo root as `AGENTS.md`. When the repo
also targets a specific framework (SAM, CDK), supplement this file with the
framework-specific template from `docs/repo-conventions/AGENTS.md.<framework>`
and merge both into a single `AGENTS.md`.

## Infrastructure as Code principles

- **SAM is the default** for new serverless workloads unless the task explicitly
  calls for CDK or raw CloudFormation.
- **Lambda defaults:** prefer Python 3.12 runtime, ARM64 architecture, 128 MB
  memory (raise only when needed with evidence), and 30-second timeout unless
  the task requires longer.
- **Exact-pin all CDK library versions.** Never use `*` or `^` ranges in
  `package.json` for `aws-cdk-lib`, `aws-cdk`, `constructs`, or any
  `@aws-cdk/*` package. Pin to an exact version (e.g. `"2.100.0"`, not
  `"^2.100.0"`).
- **Never commit** account IDs, role ARNs, VPC IDs, security group IDs, or any
  other deployment-specific identifiers. Use CloudFormation parameters or
  context values (`cdk.json` / `cdk.context.json`) with documented defaults.
- **Deploy with least-privilege IAM.** Every Lambda, Step Function, or ECS task
  gets its own scoped role. Do not reuse admin or broad-read roles across
  resources.

## Verification

- Run `cdk synth` (CDK) or `sam build && sam validate` (SAM) before pushing.
- If the repo has a `Makefile` or `package.json` script for synth/validate, use
  it instead of the bare command.