An architecture decision record (ADR) is a short document that captures one architecturally significant decision and its rationale. A project's collection of ADRs is its decision log. The practice has no single originator: Michael Nygard's 2011 blog post popularized it, and decision records were in use in the 1990s. There is no single required template.
Nygard's 2011 format
Michael Nygard described ADRs in "Documenting Architecture Decisions," a post on the Cognitect blog dated November 15, 2011. He called an ADR a short text file that describes a set of forces and a single decision in response to those forces.
He kept records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces or construction techniques.
Each record has a title, context, decision, status and consequences. Context describes the forces at play, including technological, political, social and project-local ones. Consequences lists every result of the decision, not only the positive ones.
A decision is "proposed" until stakeholders agree and "accepted" once they do. A later ADR that changes or reverses it can mark it "deprecated" or "superseded," with a reference to its replacement. A reversed decision is kept, not deleted.
ADRs are numbered sequentially and numbers are not reused. Nygard kept them in the project repository in a lightweight text format such as Markdown, and said each should be one or two pages long.
Before Nygard
Olaf Zimmermann, who worked as a consulting IT architect at IBM, writes that architectural decisions have answered "why" questions about design options since software architecture emerged in the 1990s. He writes that the IBM Global Services Method included a work product called Architectural Decisions, ARC-100, since 1998 at least.
adr.github.io, the site of the ADR GitHub organization, names Nygard's 2011 post as the one that popularized the concept.
Templates
adr.github.io lists many ADR templates, including Markdown Architectural Decision Records (MADR), Nygard's format and Y-statements. MADR records the options considered with their pros and cons.
A Y-statement fits a decision into one sentence: in the context of a use case, facing a concern, we decided for an option to achieve a quality, accepting a downside.
According to adr.github.io, the template for ISO/IEC/IEEE 42010:2011, the international standard for architecture descriptions, suggests nine information items for ADRs.
What AWS and Microsoft recommend
Microsoft's Azure Well-Architected Framework treats the ADR as an append-only log. Accepted records are not edited; a changed decision gets a new record that supersedes the original and links to it. Microsoft suggests each record include the problem and context, the options considered, the decision outcome, tradeoffs, a confidence level and a status.
AWS Prescriptive Guidance names three outcomes for ADRs: aligning current and future team members, setting a strategic direction for a project or product, and avoiding decision anti-patterns by defining how decisions are documented and communicated.
Sources
Checked November 5, 2026.
- Michael Nygard, Documenting Architecture Decisions (Cognitect blog, November 15, 2011)
- adr.github.io, Architectural Decision Records
- adr.github.io, ADR Templates
- Olaf Zimmermann, Architectural Decisions: The Making Of (April 27, 2020)
- Microsoft Azure Well-Architected Framework, Maintain an architecture decision record (ADR)
- AWS Prescriptive Guidance, Using architectural decision records to streamline decision-making during development