# Architecture Decision Records Architecture Decision Records (ADRs) are short documents that each record one architecturally significant decision. Michael Nygard proposed the format in "Documenting Architecture Decisions" (Cognitect blog, 15 November 2011). Nygard's ADR has five parts: - **Title**: a short noun phrase - **Context**: the forces at play when the decision was made - **Decision**: what was decided, in active voice - **Status**: proposed, accepted, deprecated or superseded - **Consequences**: everything that follows from the decision, good, bad and neutral ADRs live in the project's repository as plain text (Markdown), numbered sequentially, with numbers never reused. They're kept short (one or two pages at most). When a decision is reversed, the old record stays and is marked as superseded by the new one, so the history of what was decided and why remains readable. The problem ADRs solve: months later, nobody remembers why something was built the way it was, so people either follow the decision blindly or reverse it without knowing what it protected against. The format works beyond software, as a decision log for any project. The ADR GitHub organization maintains templates, including Nygard's, MADR and Y-statements. ## References - Michael Nygard, "Documenting Architecture Decisions", 2011: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions - https://adr.github.io/ - https://concepts.dsebastien.net/concept/architecture-decision-records/ ## Related - [[Design Rationale]] - [[Decision Making]] - [[DACI Decision-Making Framework]] - [[Project charter]] - [[Project Management (MoC)]]