skip to content

What is an Architecture Decision Record (ADR), and what does a typical ADR contain?

level: juniorimportance: must knowfreq 72%

answer

  1. One decision, one page, one number
  2. Context / Decision / Consequences
  3. Immutable — supersede, never edit
  4. Status: proposed → accepted → superseded
  5. Lives in the repo, reviewed in PRs

basics

~20 s

An ADR is a short document capturing one significant architecture decision: the context that forced the choice, the option chosen, and the consequences. ADRs are numbered, dated, kept in version control, and never rewritten — superseded ones stay for history.

solid answer

~50 s

An Architecture Decision Record captures a single architecturally significant decision — one that is costly to reverse or that affects structure, quality attributes, or external dependencies. The classic Michael Nygard format has: Title (short noun phrase), Status (proposed / accepted / deprecated / superseded by ADR-xx), Context (the forces, constraints, and problem — written in neutral, value-free language), Decision ("We will…"), and Consequences (both good and bad, what becomes easier and harder). Records are immutable and append-only: to change your mind you write a new ADR that supersedes the old one, so the log becomes a decision history rather than a snapshot. ADRs live next to the code in the repo (docs-as-code), are reviewed through pull requests, and are numbered monotonically. Their main value is answering "why is it like this?" months later, which prevents re-litigating settled decisions and stops new joiners from "fixing" a deliberate constraint.

code

markdown · 15 lines
markdown
# 0014. Serve read traffic from a replica

Status: accepted (2026-03-11); supersedes 0009

## Context
Report queries hold locks on the primary for 2-6 s, pushing checkout
latency past the 300 ms p99 budget. Reports tolerate ~1 min staleness.

## Decision
We will route all reporting queries to an async read replica.

## Consequences
+ Primary write latency isolated from reporting load.
- Reports may show stale data; UI must label "as of <timestamp>".
- Ops now owns replica lag monitoring and a failover runbook.

go deeper

for a junior

Name the sections (Context, Decision, Consequences, Status) and say ADRs live in the repo so the team can see why something was built that way.

for a middle

Add the immutability rule and supersession, and give a concrete criterion for what counts as architecturally significant.

for a senior

Discuss how ADRs fit governance — PR review, linkage from arc42 §9, MADR's options-considered section — and the failure modes of too many or too few records.

for a principal

Frame ADRs as the organisation's decision memory: how you seed the practice, keep signal-to-noise high across many teams, use them in onboarding and audits, and satisfy ISO/IEC/IEEE 42010's rationale requirement without heavyweight process.

## The problem ADRs solve Every system accumulates decisions: which database, whether to allow synchronous calls between services, whether authentication happens at the edge or per-module. Code shows **what** was built; it almost never shows **why**. Six months later the reasoning lives only in the heads of people who may have left. The result is *architectural amnesia*: teams either re-argue the same question repeatedly, or they "clean up" something that looked arbitrary but was actually load-bearing. An **Architecture Decision Record (ADR)** is a deliberately tiny document — usually one page — that records exactly one decision and the reasoning behind it. The idea was popularised by Michael Nygard (2011). A directory of ADRs is called a **decision log** or ADR log. ## Terminology, defined - **Architecturally significant decision**: one that is expensive to reverse, affects the structure of the system, affects a **quality attribute** (a measurable non-functional property such as latency, availability, security, or modifiability), or creates a dependency on something outside your control. Choosing a naming convention for local variables is *not* significant; choosing to make a module boundary transactional *is*. - **Status**: the lifecycle state of the record. Common values: `proposed` (under discussion), `accepted` (in force), `deprecated` (no longer applies, nothing replaced it), `superseded by ADR-0031` (a newer decision replaced it). - **Immutable / append-only**: you do not edit the Decision or Context of an accepted ADR. You only ever flip its Status and write a *new* ADR. This is what turns the collection into a history you can read chronologically. ## The canonical structure 1. **Title** — a short noun phrase, e.g. "0014. Use append-only Liquibase changesets for schema migrations". Numbered so it can be cited ("see ADR-0014"). 2. **Status** — as above; plus date. 3. **Context** — the forces at play: requirements, constraints, existing commitments, team skills, deadlines, regulatory rules. Written in **value-free, neutral language**: state facts and tensions, not the conclusion. A good Context makes the decision feel almost inevitable to the reader. 4. **Decision** — stated in active voice: "We will …". One decision per record. 5. **Consequences** — the resulting situation, **both positive and negative**. "Easier: …", "Harder: …", "We now must: …". This section is what stops ADRs from being marketing documents. Consequences may themselves be new problems that later get their own ADRs. Optional sections seen in practice: *Options considered* (with why each was rejected — the MADR template, "Markdown Any Decision Record", formalises this), *Assumptions*, *Review date*, *Related decisions*. ## Where ADRs live and how they are governed - In the repository, typically `docs/adr/0001-title.md`, so they are versioned with the code and change through the same pull-request review as code. This is the **docs-as-code** practice. - Tooling exists (e.g. `adr-tools`, or template repos) to scaffold a new record, renumber, and mark supersession — but plain Markdown files are entirely sufficient. - Many teams add a lightweight rule: any PR that changes a boundary, a dependency, or a quality-attribute trade-off must link an ADR. ## Trade-offs and failure modes - **Too many ADRs**: recording trivia dilutes the log until nobody reads it. Filter on "architecturally significant". - **Too few**: the log becomes a museum of three decisions from the first month, which is worse than none because it implies coverage that doesn't exist. - **Editing history**: mutating old ADRs destroys the main benefit — you can no longer reconstruct what the team believed at the time. - **Decision without consequences**: omitting the negatives makes the record useless for the next reader, who needs to know what pain to expect. - **ADRs as a replacement for architecture description**: they are complementary. ADRs give *rationale over time*; views/diagrams (arc42, C4, 42010 views) give *structure right now*. You need both. ## Relationship to standards ISO/IEC/IEEE 42010 (the standard for architecture description) explicitly requires **architecture rationale** to be recorded, including considered alternatives. ADRs are the most common lightweight way to satisfy that requirement. arc42 has a dedicated section 9 "Architecture Decisions" that is usually just a link to the ADR log.

  • How do you decide whether a decision deserves an ADR at all?
    Ask three questions: is it expensive or slow to reverse, does it change a structural boundary or an external dependency, and does it trade one quality attribute against another (e.g. consistency vs. latency)? A "yes" to any of those makes it architecturally significant. Reversible, local, single-team-internal choices should not get ADRs — recording them buries the important ones in noise.
  • What do you do when a decision recorded in an accepted ADR turns out to be wrong?
    Write a new ADR that states the new decision and references the old one, then set the old record's status to "superseded by ADR-nn". You do not delete or rewrite the original: its Context explains what the team knew at the time, and the pair of records together shows what changed (new load, new constraint, new information), which is far more instructive than a silently corrected page.
  • How do ADRs relate to a full architecture document like arc42?
    They are orthogonal. arc42 (or any architecture description) tells you the current structure — building blocks, runtime scenarios, deployment, cross-cutting concepts. ADRs tell you the reasoning trail that produced that structure. Most teams keep arc42 section 9 as little more than an index into the ADR log, which keeps the big document stable while the decision history grows independently.

An ADR is like the ship's log rather than the ship's blueprint. The blueprint shows the current vessel; the log tells you why the captain turned left at the storm — including the entries that later turned out to be mistakes, which are exactly the ones you most want to read.

saying these in an interview costs you the question

  • Saying ADRs should be edited in place when the decision changes — that destroys the decision history that is their entire point.
  • Recording only the positives in Consequences; an ADR with no downsides listed is a sales pitch, not a record.
  • Claiming ADRs replace diagrams/views — rationale and structure answer different questions.
  • Writing the Context so it already argues for the chosen option; Context should state forces neutrally.
  • Treating every technology choice as ADR-worthy, producing hundreds of records nobody reads.
  • Storing ADRs in a wiki disconnected from the code, where they drift out of sync with the repository.

context

resolving links…