The choice whose reason nobody knows any more
Someone joins a project and finds a technical choice that baffles them. Michael Nygard starts from this situation in “Documenting Architecture Decisions” (15 November 2011), the blog post which, according to the adr.github.io website, popularised the architecture decision record. Without knowing the reasons for and consequences of the decision, he writes, that person has only two options: accept it blindly, although the context may have changed, or change it blindly, at the risk of undoing what it protected.
Definition of the architecture decision record
The expression, abbreviated to ADR, refers to a record of an architecture decision. Michael Nygard describes the ADR as a short text file, which sets out a set of forces and a single decision taken in response. He reserves the format for decisions he calls “architecturally significant”: those that affect the structure, non-functional characteristics, dependencies, interfaces or construction techniques.
The adr.github.io website writes “architectural decision record”: an ADR there records a single architecture decision and its justification, and a project’s ADRs form its decision log. These sources were read on 12 November 2026.
Five sections, numbered files that are never erased
The blog post sets five sections, quoted under their original names.
- Title: a short noun phrase.
- Context: the forces at play, technical, political or social, described in neutral terms.
- Decision: the response adopted, in full sentences.
- Status: proposed or accepted, then deprecated or superseded if a later ADR revisits the decision.
- Consequences: the context resulting from the decision, including negative and neutral effects.
ADRs are stored in the project repository, in a lightweight text format (Markdown or Textile, for example), and are numbered sequentially. A reversed decision keeps its ADR, marked as superseded. Each ADR fits on one or two pages, written as a conversation with a future developer.
This entry’s reading, not the blog post’s: a deliberate shortcut, that is, intentional technical debt, belongs among the consequences.
MADR, Y-statement: other templates, and an objection
The adr.github.io website lists other templates. MADR (Markdown Architectural Decision Records) adds the options considered, with their pros and cons. The Y-statement reduces the decision to one sentence: in such a context, facing such a concern, such an option is chosen to achieve such a quality, at the cost of such a drawback. The website also cites command-line tools, including adr-tools and Log4brains.
Michael Nygard reports an objection: stored with the code, ADRs are less accessible to project managers and stakeholders who do not use the repository. He answers it by sharing links to the repository.
ADR, architecture document, C4 diagrams: not to be confused
An architecture document sets out, for an entire project, the requirements, the options studied and the solution adopted. An ADR covers a single decision.
A diagram shows a structure without saying why it was chosen: the diagrams of the C4 model describe the containers and components of a system, the ADR keeps the reason for a breakdown.
An ADR applies to a given project; principles common to all projects fall within enterprise architecture.
Example: offline data entry at an agricultural cooperative
Suppose an agricultural cooperative is developing the mobile application for its collection drivers. ADR 4, “Offline entry of weighings”, sets out the context: silos with no network coverage. The decision: the application records weighings on the phone and transmits them when the network returns. The consequences: the stock known at head office lags behind the field, and duplicates will have to be reconciled. Later, the silos are covered: an ADR 19 adopts online entry, and ADR 4 moves to the status “superseded”.
Our page IT architecture counts such a register among its deliverables, alongside the architecture document.