ADR (architecture decision record)
- Status
- Review
- Version
- 1.0.1
- Authority
- Not stated
- Applies to
- Core
Definition
An ADR (architecture decision record) is a short, numbered file kept next to the code that records one significant, hard-to-reverse decision: the context, the options considered, the choice and its consequences. An accepted ADR is not edited in substance; a changed decision gets a new ADR that supersedes the old one.
Michael Nygard proposed the practice in 2011; MADR is a Markdown template for it, with fields for the options, the outcome, the consequences and the way the decision will be confirmed. A decision that is hard to reverse is marked as one the owner takes (see Roles and decision rights).
Example
0007-store-sessions-in-redis.md with status accepted, three considered options and a measured result. Hub projects keep them in project/decisions/, written from templates/adr.md.
Related
- Architecture decision records — the rules for writing and changing ADRs.
- Blueprint — where the choices are marked.
- Roles and decision rights — which decisions are the owner’s.
Sources
- Michael Nygard, “Documenting Architecture Decisions” (2011) — all rights reserved; summarised, not copied. Accessed 2026-11-20.
- MADR 4.0.0 — Markdown Architectural Decision Records — MIT OR CC0-1.0; summarised, not copied. Accessed 2026-11-20.