Manu's Vault

Architecture Decision Records

3 min readStatus:Seedling

Core Idea

Architecture Decision Records (ADRs) document significant architectural decisions along with their context, rationale, and trade-offs. Unlike traditional documentation, ADRs capture the “why” and enable knowledge flow through time, helping future developers understand not just what was decided but why alternatives were rejected.

What Are ADRs?

  • Short document (1-2 pages) capturing a single architecturally significant decision
  • Immutable once written—new decisions get new ADRs
  • Numbered sequentially (ADR-001, ADR-002, etc.) and stored in version control with the code
  • Written at the time the decision is made

Architecturally significant decisions are those that affect the structure, characteristics, or dependencies of the system; are difficult or costly to reverse; have long-term impact; or require understanding by future developers. Not every decision qualifies.

Core Structure

ADRs follow a consistent four-part template: Status (Proposed/Accepted/Superseded), Context (what situation forced the decision), Decision (what was chosen and why, including alternatives rejected), Consequences (positive and negative results). See ADR-Format-and-Structure for the full breakdown.

Why ADRs Matter

Traditional documentation describes what exists—not why. Future developers hitting a system built with event sourcing have no idea if the pattern was deliberate or accidental. ADRs solve this by capturing reasoning that would otherwise decay into tribal knowledge.

ADRs enable knowledge flow through time (decisions today inform developers tomorrow), through teams (new members get up to speed without asking around), and through reversal (when context changes, engineers can see the original rationale and create a new ADR superseding the old one).

When to Write an ADR

Write one when: the decision will be hard to reverse; future developers will wonder “why?”; multiple viable alternatives exist; the decision affects multiple teams; significant trade-offs are involved.

Skip it for: trivial decisions easily reversed; obvious choices with no real alternatives; frequently-changing implementation details.

Common Anti-Patterns

  • Covering your assets: Documenting vaguely to deflect blame
  • Groundhog Day: No ADR means the same debate resurfaces every few months
  • Email-driven architecture: Decisions buried in email threads, invisible to most of the team
  • ADR novels: 10-page documents no one reads—keep to 1-2 pages
  • Never revisiting: Old ADRs remaining “Accepted” forever; mark as “Superseded” when context changes

Sources

Note

This content was drafted with assistance from AI tools for research, organization, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.

Graph View

Backlinks