What is an Architecture Decision Record (ADR), what does it contain, and why is capturing the rationale for a style choice as valuable as the choice itself?
answer
- one decision, one page, numbered
- context → decision → alternatives → consequences
- immutable: supersede, never edit
- consequences must include the costs
- state the revisit trigger
basics
~20 sAn ADR is a short document recording one significant architecture decision: the context, the options considered, the decision, and its consequences. It matters because it preserves why something was chosen, so later teams can tell a deliberate trade-off from an accident.
solid answer
~50 sAn ADR is a small, immutable, numbered document stored with the code, capturing one decision. Typical sections: title, status (proposed / accepted / deprecated / superseded by ADR-0012), context (the forces, constraints and drivers), decision stated actively ('we will…'), alternatives considered with why each was rejected, and consequences — both the benefits and the costs being accepted. ADRs are append-only: you never edit an accepted one, you supersede it, so the history stays honest. Their value is that architecture erodes when rationale is lost: without it, a later team cannot distinguish a constraint that still holds from one that expired, so they either cargo-cult a bad decision or rip out a load-bearing one. A good ADR also states the revisit trigger — the condition (a scale threshold, a team-count threshold, a regulatory change) that should reopen the decision.
go deeper
Define it as a short document per decision containing context, the decision and its consequences, kept with the code, and say it explains why so later teams are not guessing.
Add status and supersession, alternatives with rejection reasons, and the immutability rule; give an example of a decision worth recording versus one that is not.
Stress consequences including costs, the revisit trigger, and how lost rationale causes both cargo-culting and reckless removal. Mention keeping ADRs reviewable in pull requests.
Position ADRs within a lightweight governance model: who accepts them, how they relate to RFCs and architecture review, how they feed fitness functions, and how to keep the log alive without creating bureaucracy.
### What it is An **Architecture Decision Record**, popularised by Michael Nygard, is a lightweight document — usually one page of Markdown in the repository, named like `0007-adopt-modular-monolith.md`. One record, one decision. The set of records forms a **decision log**. ### Canonical sections - **Title** — a short noun phrase naming the decision. - **Status** — `proposed`, `accepted`, `deprecated`, or `superseded by ADR-00NN`. Status is the only field that changes after acceptance. - **Context** — the forces: business drivers, ranked quality attributes, constraints (team size, budget, deadline, compliance), and what is currently true. This is the section future readers actually need. - **Decision** — stated actively and unambiguously: "We will build a single deployable modular monolith with one schema per module." - **Alternatives considered** — each realistic option with the reason it lost. This is what stops the same debate recurring every six months. - **Consequences** — what becomes easier *and* what becomes harder. An ADR with only positive consequences is a sales pitch, not a decision record. ### Why rationale beats the decision A decision without its context is unfalsifiable later, which produces two failure modes. **Cargo-culting**: the team preserves a rule long after the reason expired — for example everything goes through a message broker because of a vendor integration retired years ago. **Reckless removal**: a team deletes something that looks pointless but was load-bearing, such as a seemingly redundant boundary that exists for a compliance audit. Recording the *forces* lets a future reader re-run the reasoning against today's facts and decide correctly either way. ### Practices that make ADRs work - **Immutability.** Never rewrite an accepted ADR; write a new one that supersedes it. The wrong turn is part of the value. - **Locality.** Keep them in the repository so they version with the code and are reviewable in a pull request. - **Timing.** Write when the decision is made, not retrospectively at the end of a project; write drafts as `proposed` to drive the discussion. - **Significance filter.** Record decisions that are costly to reverse or that constrain many future choices — style, boundaries, datastore, consistency model, auth model — not library micro-choices. - **Revisit trigger.** State explicitly what would invalidate the decision: "revisit if a single module exceeds 30 % of total CPU", "revisit beyond four autonomous teams". This turns a static document into a tripwire. ### Edge cases and limits ADRs do not replace architecture documentation — they are a *changelog of reasoning*, not a description of the current system; a reader still needs an overview and diagrams. They also decay if nobody references them: link ADR numbers from code comments, pull requests and design docs so they stay live. And an ADR is not a governance gate by itself; a decision still needs the right people involved before its status flips to `accepted`.
- Which decisions deserve an ADR and which do not?Record decisions that are expensive to reverse or that constrain many downstream choices: architectural style, module or service boundaries, datastore and consistency model, authentication approach, public contract conventions. Skip easily reversible, locally scoped choices such as a formatting rule or a swappable utility library.
- An accepted ADR turns out to be wrong. What do you do with it?Leave it untouched and write a new ADR that supersedes it, updating the old one's status to 'superseded by ADR-00NN'. Editing history hides the reasoning that led to the mistake, which is exactly the information that prevents repeating it.
Like a surgeon's operative note: not just 'removed the appendix' but the symptoms, what else was suspected and ruled out, and what to watch for afterwards — so the next clinician can act without guessing.
saying these in an interview costs you the question
- ADRs that record only the decision, with no alternatives and no negative consequences
- Editing or deleting accepted ADRs instead of superseding them
- Writing all ADRs retrospectively at project end, when the forces have been forgotten
- Recording trivial, easily reversible choices until the log becomes noise nobody reads
- Treating the ADR set as the system's architecture documentation rather than a log of reasoning