Architecture Decision Records

Lightweight documentation for architecturally significant decisions.

Core Principle

"Document the why, not just the what."

Code shows what was built; ADRs explain why it was built that way.

What Makes a Decision "Architecturally Significant"?

ADR Format

Required Sections

ADR Best Practices

1. One decision per ADR - Keep focused
2. Mark as superseded, do not delete - deleting an ADR breaks every inbound reference (PRs, READMEs, other ADRs) and erases the historical reasoning future engineers need to understand the present state
3. Number sequentially - reusing a number invalidates every existing reference to the prior decision and produces silent collisions in tooling that keys on ADR ID
4. Keep them short - 1-2 pages maximum
5. Write when deciding - Not after the fact
6. Link to research - Traceability to evidence

When NOT to Write an ADR

• Trivial decisions (naming conventions, formatting)
• Decisions already covered by team standards
• Temporary/experimental decisions
• Decisions with obvious single answers

Status Lifecycle

Proposed → Accepted → [Deprecated | Superseded by ADR-XXX]

RCA & Alternatives Capture

Two ADR-adjacent practices keep decision records auditable: the RCA Verification Matrix (V1/V2 evidence-graded claim list with file/line targets — pause and draft this before prose) and the Alternatives Capture Table (≥2 rejected options with pros/cons/why-not, even when the choice feels obvious). See reference.md → "RCA Verification Matrix" and reference.md → "Capturing Alternatives" for the full patterns and the table schema.

API Consumption Patterns

Prefer the backend's atomic nested-create endpoint (parent + children in one transactional request) over create-parent-then-loop-children. The split form orphans the parent on child failure and duplicates it on retry. Verify the contract first (grep route handlers or curl the schema) before assuming separate endpoints are required.

Server-side rationale lives in arch-ddd § "Aggregate Write Boundaries — Client Side" — cross-reference rather than duplicating transaction semantics here. See reference.md § "API Consumption Patterns" for verification steps.

See reference.md for: Weighted Dimensions / MCDM axis-grounding, Adapter-Lie Smell, Architecture Comparisons Age Unevenly (fast/slow churn taxonomy, CNCF probe), Migration Patterns (migration-before-deletion), Feasibility POC Discipline (four practices).