Architecture Decision Records

An Architecture Decision Record (ADR) is a short document capturing an important architectural decision, its context, the options considered, and the rationale for the choice made. Pioneered by Michael Nygard and popularized by ThoughtWorks, ADRs address the problem of "archaeology" — new engineers spending weeks reconstructing why the architecture is the way it is from commit history and tribal knowledge. A good ADR has five sections: Title, Status (Proposed/Accepted/Deprecated/Superseded), Context (forces driving the decision), Decision (what was chosen and why), Consequences (trade-offs accepted). ADRs are stored in the repository (typically `docs/architecture/decisions/`) and treated as first-class code artifacts.

Key Points

• ADRs are immutable once accepted — you never edit a past decision; you create a new ADR that supersedes the old one, preserving the history of how thinking evolved.
• ADR lifecycle: Proposed (under discussion) → Accepted (approved by relevant stakeholders) → Deprecated (still in place but being phased out) → Superseded (replaced by a newer ADR).
• Short format ADRs (Nygard style) take 15-30 minutes to write — the investment compounds by eliminating repeated debate of settled decisions as team membership changes.
• Decision options section should list 2-4 real alternatives with their pros/cons — a decision with only one option listed signals insufficient analysis and weakens the record.
• ADRs prevent "HiPPO-driven architecture" (Highest Paid Person's Opinion) — by requiring written context and consequences, the decision is evaluated on merit, not authority.
• Architectural fitness functions (from "Building Evolutionary Architectures") can be added to ADRs as automated checks — "this decision requires test X to remain green" creates living accountability.
• Tools: adr-tools CLI (Michael Nygard), Log4Brains (rich web UI for browsing ADRs), Backstage (Spotify's developer portal) supports ADR documentation as a first-class feature.
• ADRs should be reviewed in architecture reviews and referenced in pull request descriptions — "this PR implements ADR-0042: use Kafka for async communication" creates traceability from code to decision.