Architecture Decision Records (Summary)
In one line: ADRs capture the reasoning behind significant decisions — context, alternatives, consequences — which is what future readers need to judge whether a decision still applies.
Architecture Decision Records capture the reasoning behind significant technical decisions. The decision matters less than the context, alternatives, and consequences.
When to Write an ADR:
| Change Type | ADR Required | Rationale |
|---|---|---|
| Technology choice (database, framework, library) | Yes | Affects entire codebase; alternatives have different tradeoffs |
| Architectural pattern (REST vs GraphQL, ORM vs raw SQL) | Yes | Shapes all subsequent implementation |
| Data model decisions (schema design, multi-tenancy approach) | Yes | Irreversible in production without migration effort |
| Integration approach (synchronous vs async, polling vs webhooks) | Yes | Affects performance, reliability, and operational complexity |
| Security decisions (auth mechanism, encryption, RLS policy) | Yes | High-stakes; wrong choices have regulatory consequences |
| Bug fixes, minor refactoring, configuration changes | No | Tactical changes that do not constrain future decisions |
ADR Template: Title, Date, Status (Proposed / Accepted / Deprecated / Superseded by ADR-YYYY), Context (what issue motivated this decision), Decision (what change is being made), Consequences (positive, negative, neutral), Alternatives Considered (with rejection rationale).
Supersession Tracking: When an ADR is superseded, the original ADR's status is updated to "Superseded by ADR-YYYY" and the new ADR references the old one. This creates a traceable decision chain — anyone reading ADR-0008 (raw SQL) can follow the link to the ORM Repository pattern that replaced it, including the reasoning for the change.
Evidence: The register integrity is checked mechanically by scripts/check-adr-register.sh in CI (also surfaced by the consolidation census, Section 2.8) — a dangling supersession reference or a missing ADR fails the check. Reproducible: reference a non-existent ADR and watch CI fail. See appendix-g-adr.md.
Full specification: appendix-g-adr.md