## 1. Source Identity ### *Documenting Architecture Decisions* ### Michael Nygard, Cognitect blog, November 2011 ### Origin of the modern ADR template ## 2. The Template ### Title — description of the decision (not the problem) ### Status — proposed / accepted / deprecated / superseded ### Context — forces and background ### Decision — the central decision in response to those forces ### Consequences — resulting context, positive *and* negative *and* neutral ## 3. Storage Convention ### Repo location: `doc/arch/adr-NNN.md` ### Sequential numbering, never reused ### One ADR per file ## 4. Why It Matters Now (2026 Context) ### ADRs are immune to context compaction — they live on disk ### They are the canonical Layer-1 memory for agents (see Layered Memory Architecture) ### Consequences section is where load-bearing operational rules survive ## 5. Variants ### MADR (Markdown ADRs) ### Y-Statements (Olaf Zimmermann) ### Nygard remains the most widely used ### References - https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions - https://adr.github.io/ - https://github.com/joelparkerhenderson/architecture-decision-record