Appearance
Decision Guides
Compare options before you adopt them in your project. Record the outcome in your repo's ADRs — not here.
Each guide includes:
- The decision — what you're choosing and why it matters
- Options compared — pros, cons, fit
- Pitfalls — common failures when implementing
- Suggested starting point — for teams new to AI-native delivery
| # | Guide | Key question |
|---|---|---|
| 1 | AI coding tools | Which AI assistant(s) for daily development? |
| 1b | AI toolkit catalog | All AI + adjacent tools (ADR, MCP, specs) in one place |
| 2 | Planning, ADR & specs | How do AI, ADRs, and specs fit in planning? |
| 3 | Knowledge indexing & portals | How do teams and agents discover ADRs and specs? |
| 4 | Spec-driven development | How tightly should specs bind AI-generated code? |
| 5 | Automated testing & QA | What to automate; what stays human? |
| 6 | Linters & static analysis | ESLint, Ruff, SAST, SCA, pre-commit, Spectral? |
| 7 | AI guardrails & security | Policy, AI review, data in prompts |
| 8 | CI/CD & release | How do changes reach AWS safely? |
| 9 | Runtime on AWS | Where do services run? |
| 10 | Monitoring, tracing & logging | Metrics, logs, traces, RUM, synthetics? |
| 11 | Dashboards & reporting | On-call, SLO, exec, audit views? |
| 12 | Incident management | Paging, severity, comms, runbooks? |
| 13 | Observability & monitoring QA | How does prod monitoring feed dev quality? |
| 14 | Data governance layers | Classification, lineage, AI data bounds? |
| 15 | Human-in-the-loop & governance | Where must humans decide? |
| 16 | Identity, access & secrets | SSO, IAM, RBAC, Secrets Manager, CI OIDC? |
Quick comparison matrix
| Area | Option A | Option B | Option C | See guide |
|---|---|---|---|---|
| IDE AI | Cursor + MCP | Amazon Q | GitHub Copilot | #1 |
| ADR home | Git docs/adr/ | Confluence | Backstage only | #2 |
| Agent context | OpenSearch RAG | Kendra | MCP read Git | #3 |
| Contract | OpenAPI | Protobuf + buf | BDD only | #4 |
| Linters / SAST | ESLint + Ruff | golangci-lint | Semgrep + CodeQL | #6 |
| CI orchestrator | CodePipeline | GitHub Actions | GitLab CI | #8 |
| Compute | ECS Fargate | EKS | Lambda | #9 |
| Metrics/logs/traces | CloudWatch + X-Ray + OTel | Datadog | AMP + AMG | #10 |
| Dashboards | CloudWatch / Grafana | Datadog | QuickSight (exec) | #11 |
| Incidents | PagerDuty | Opsgenie | AWS Incident Manager | #12 |
| Data catalog | Glue + Macie | Collibra | DataZone | #14 |
| Identity / secrets | IAM Identity Center + SM | Cognito + custom RBAC | OIDC CI only | #16 |