Architecture Decision Records (ADRs)
This directory holds Architecture Decision Records — one file per architecturally significant decision, capturing the context, the choice, and its consequences.
Why this exists alongside the decisions log
docs/context/07-decisions.md is the fast, one-line index of every decision
(D1, D2, …). It answers "what was decided?" at a glance.
ADRs answer "why, and at what cost?" They are the long-form record for the subset of decisions that are architectural — i.e. expensive to reverse, affecting structure, cross-cutting concerns, or external contracts. The repo conventions (CLAUDE.md §3 and DoD #5) require an ADR link when a PR is architectural.
Not every D-row needs an ADR. Pricing, tooling-vendor, and process decisions stay in the log only. A decision earns an ADR when reversing it would ripple across modules.
Conventions
- Filename:
NNNN-kebab-title.md, zero-padded sequence (0001-…). - Status:
Proposed→Accepted→ (Superseded by NNNN|Deprecated). - Cross-link: every ADR references the
D#rows it formalizes; the decisions log may link back. Superseding ADRs link the one they replace. - Immutable once Accepted: don't rewrite history — supersede with a new ADR.
- Copy
0000-template.mdto start a new one.
Index
| ADR | Title | Status | Formalizes |
|---|---|---|---|
| 0001 | Azure-first, cloud-agnostic by contracts | Accepted | D6, D18, D19 |
| 0002 | Kyverno as the Kubernetes policy engine | Accepted | D5 |
| 0003 | OIDC federation over long-lived cloud secrets | Accepted | D22, D26 |
| 0004 | Terraform remote state on Azure Blob | Accepted | D3, D22 |