What is an Architecture Decision Record (ADR), and what are the four core sections of Michael Nygard's classic ADR template?
answer
- Nygard 2011: Status, Context, Decision, Consequences
- One decision, one file, numbered, in git
- Context = neutral forces; Decision = "We will…"
- Consequences include the bad news
- Immutable — supersede, don't edit
basics
~20 sAn ADR is a short document recording one significant architecture decision and why it was made. Nygard's template has four sections: Context (the forces at play), Decision (what we chose), Status (proposed/accepted/superseded), and Consequences (what results, good and bad).
solid answer
~50 sAn Architecture Decision Record is a small, dated, numbered document capturing a single architecturally significant decision at the moment it is made. Michael Nygard's 2011 template has four core sections: **Status** (proposed, accepted, deprecated, superseded), **Context** (the forces — technical, organisational, budgetary — that make a decision necessary, stated neutrally as facts), **Decision** (the choice, written in active voice: "We will…"), and **Consequences** (everything that follows, positive, negative and neutral — the new constraints the team now lives under). A title line identifies the decision. ADRs live in the codebase (commonly `docs/adr/NNNN-title.md`), are versioned with the code, and form an append-only log: you do not rewrite an accepted ADR, you supersede it with a new one. Their purpose is to preserve rationale so future maintainers understand *why* the system looks the way it does, not just what it does.
code
markdown · 21 lines# 7. Use PostgreSQL for the catalog store
## Status
Accepted (2026-02-11). Superseded by ADR-0019 (2026-07-03).
## Context
Catalog writes must be atomic across three tables. Team has strong SQL
experience, no operational experience with document stores. Managed
PostgreSQL is already part of our hosting plan at no extra cost.
Expected data volume < 50 GB for the next two years.
## Decision
We will store catalog data in PostgreSQL, accessed only through the
Catalog module's public API.
## Consequences
+ Multi-table writes get real transactions; no compensating logic.
+ Reuses existing backup/monitoring tooling.
- Every environment, including CI, now needs a PostgreSQL instance.
- Schema evolution requires reviewed migrations, slowing small changes.
- Free-text search will need a separate solution if requirements grow.go deeper
Name the four sections and say the point is preserving why, not what. One decision per numbered file, kept in the repo.
Add the conventions: active-voice "We will…", neutral Context, honest negative Consequences, immutability with supersede-don't-edit, and PR review alongside the code.
Discuss what qualifies as architecturally significant, how ADRs feed onboarding and reviews, and how the log stays alive (superseding chains, an index, periodic pruning of stale Proposed records).
Frame ADRs as the artefact of a decision process: who may accept, how they interact with RFCs and an architecture advice process, how consequences become fitness functions or automated architecture tests, and how the log supports audits and org-wide reuse.
## The problem ADRs solve Every system carries decisions that are expensive to reverse: which data store, whether to split a service, how modules may depend on each other, what authentication scheme to use. Six months later a new engineer asks "why on earth is it done this way?" The code shows *what* was built; it almost never shows *why*, nor what was considered and rejected. Without that rationale, teams do one of two harmful things: - **Blind reversal** — they undo a decision without knowing the constraint that forced it, and rediscover the pain. - **Blind preservation** — they treat an accidental choice as sacred and build around it forever, long after the reason expired. This lost rationale is sometimes called *architectural knowledge vaporisation*. An Architecture Decision Record (ADR) is the cheapest known antidote: a one-page document per decision, written when the decision is fresh, stored next to the code. ## Definitions - **Architecture decision** — a choice that addresses a significant requirement or constrains the system's structure. "Significant" typically means costly to change later (see *architecturally significant* below). - **ADR (Architecture Decision Record)** — the document capturing exactly one such decision. - **Decision log / decision record repository** — the ordered collection of all ADRs for a system. - **Nygard template** — the original, minimal ADR format published by Michael Nygard in the 2011 post "Documenting Architecture Decisions". It is the default that most other templates (MADR, Y-statements, Tyree & Akerman) extend or compress. ## The four core sections A Nygard ADR is a small Markdown file with a title (e.g. `0007-use-postgresql-for-the-catalog.md`) and these sections: ### 1. Status Where the decision stands in its lifecycle. The usual values are **Proposed** (drafted, awaiting agreement), **Accepted** (in force), **Deprecated** (no longer recommended but nothing replaces it), **Superseded by ADR-00NN** (replaced), and sometimes **Rejected** (considered and declined — still worth keeping, because it records that the idea was evaluated). ### 2. Context The forces at play, written as **neutral facts, not as advocacy**: functional and quality requirements, team skills, existing systems, licensing costs, regulatory constraints, deadlines. A good Context is value-free — it should read the same whichever option was eventually chosen, so that a reader can judge whether the *forces* still hold today. Include the ones that pull in opposite directions; that tension is what makes the decision a decision. ### 3. Decision The choice itself, stated in **active voice, present/future tense**: "We will store catalog data in PostgreSQL and expose it only through the Catalog module's public API." Nygard's phrasing convention ("We will…") matters: it signals a commitment made by a team, not a suggestion. Keep it to a few sentences; the reasoning belongs in Context, the fallout in Consequences. ### 4. Consequences Everything that becomes true *because* of the decision — **positive, negative and neutral alike**. "We gain transactional integrity across catalog writes" sits beside "we now operate a relational database in every environment, including CI" and "schema changes require migrations reviewed by two people". The negative consequences are the most valuable part and the most frequently omitted; they are what a future reader needs in order to weigh a reversal, and they often become the Context of a later ADR. ## Practical conventions - **One decision per file.** A file covering five decisions cannot be superseded cleanly. - **Sequential numbering, never reused**, plus a short slug: `0001-record-architecture-decisions.md` (traditionally the first ADR is the decision to use ADRs at all). - **Stored in version control, in the repository the decision affects** — commonly `docs/adr/` or `doc/architecture/decisions/`. Being in git means the ADR is reviewed in the same pull request as the code that implements it, and it travels with a fork or a repo split. - **Immutable once accepted.** Edits are limited to fixing typos and changing Status/adding a link to the superseding record. To change the decision, write a *new* ADR whose Context explains what changed, and mark the old one `Superseded by ADR-00NN`. This preserves the historical reasoning — the log is a ledger, not a wiki page. - **Short.** One or two pages. If it needs ten, it is either several decisions or a design document with an ADR hiding inside it. - **Written at decision time, by the people deciding.** Retrofitting ADRs months later produces rationalisation, not rationale — though back-filling a handful of key legacy decisions is still better than nothing. ## What an ADR is not - Not a design document or spec — it records a *choice*, not a full solution. - Not a task ticket — tickets track work; ADRs track commitments and their reasons. - Not a diagram store — diagrams may be linked, but the ADR's payload is prose rationale. - Not a policy for approval gates by itself — governance (who accepts an ADR) is a separate process layered on top. ## Cost/benefit The cost is roughly 30–60 minutes of writing per significant decision. The benefit is measured years later: onboarding time, avoided re-litigation of settled questions, and the ability to answer auditors or a new CTO with "here is the reasoning, here is what we rejected". Because the cost is per *significant* decision only, the log for a mature system is usually tens of records, not hundreds.
- Where should ADRs be stored, and why does that choice matter?In version control, in the repository whose architecture they constrain (typically `docs/adr/`). That keeps the record reviewable in the same pull request as the implementing code, versioned alongside it, and available offline to anyone who clones the repo — unlike a wiki, which drifts, loses permissions, and cannot be diffed against the code it describes.
- What goes in the first ADR of a new project?By convention, ADR-0001 records the decision to use ADRs themselves: the context (rationale keeps getting lost), the decision (we will record architecturally significant decisions as numbered Markdown files in `docs/adr/`), and the consequences (small ongoing writing cost, need for a review step). It bootstraps the practice and demonstrates the format.
An ADR is a ship's log entry, not a map. The map (the architecture diagram) shows where you ended up; the log says "18:00, storm to the north, chose the southern passage, cost us two days but kept the cargo dry." Months later the map alone can't tell you whether the southern passage was wisdom or whim.
saying these in an interview costs you the question
- Calling any technical choice an ADR — a library-version bump or a variable-naming rule is not architecturally significant
- Omitting the Consequences section, or listing only the benefits (this turns an ADR into a sales pitch)
- Editing an accepted ADR to reflect a new decision instead of superseding it, destroying the history the log exists to preserve
- Writing Context as advocacy for the chosen option rather than as neutral forces
- Bundling many decisions into one document so none can be superseded independently
- Storing ADRs in a wiki or shared drive detached from the code they govern