Skip to content
Technology transformation expertise firm · ARDIANE Group Innovate, secure, succeed

Glossary

Architecture decision record (ADR): definition, sections and related documents

Domain

Engineering

In brief

An architecture decision record (ADR) is a short document that records an architecture decision, the context that motivated it and its consequences. Michael Nygard described the format in a blog post of 15 November 2011; a project's ADRs, numbered and kept even when superseded, form its decision log.

Page contents

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.

FAQ

Frequently asked questions

Another question? Ask us

What does ADR stand for?

ADR stands for architecture decision record. An architecture decision record is a short document that records an architecture decision, the context that motivated it and its consequences. Michael Nygard described the format in the blog post "Documenting Architecture Decisions", dated 15 November 2011. The adr.github.io website calls the set of ADRs created and maintained in a project its decision log.

What does an ADR contain?

In the format described by Michael Nygard, an ADR has five sections: a title, the context, the decision, the status and the consequences. The context sets out the forces at play in neutral terms, the decision is stated in full sentences, and the consequences include negative effects. The adr.github.io website lists other ADR templates, including MADR and the Y-statement.

What happens to an ADR when the decision changes?

In the format described by Michael Nygard, an ADR whose decision is reversed is not deleted. It is kept and marked as superseded, with a reference to the ADR that succeeds it. ADRs are numbered in the order of their creation and a number is never reused, so the log keeps the sequence of decisions.

A project to bring to completion?

A first conversation is enough to understand your challenge, identify the right people and tell you frankly what we can bring.