## Definition An **Architecture Decision Record (ADR)** is a short, versioned document capturing one significant architectural decision: its context, the decision itself, and its consequences. Template originated by Michael Nygard in 2011 — see [[Documenting Architecture Decisions (Nygard)]]. ## Template (Nygard) ```markdown ## ADR-NNNN — <title describing the decision> **Date:** YYYY-MM-DD **Status:** Proposed | Accepted | Deprecated | Superseded by ADR-MMMM ### Context The forces and background information. ### Decision The central decision in response to those forces. ### Consequences Resulting context after applying the decision — positive, negative, and neutral. ``` ## Why It Matters in the Agentic Era ADRs are **immune to [[Context Compaction]]** — they live on disk and re-enter context as files when needed. They are the canonical **Layer 1** in a [[Layered Memory Architecture]]. The **Consequences** section is the load-bearing part: it captures the operational rules a future agent (or human) needs to honour. Make it specific — paths, file patterns, forbidden alternatives, re-test triggers. ## Storage Convention - Single file `docs/DECISIONS.md` with `## ADR-NNNN — ...` sections, or - One file per ADR under `docs/arch/adr-NNNN.md`. - Sequential numbering, never reused. - Linked from [[AGENTS.md Convention File]] so every session knows where to look. ## Status Lifecycle - **Proposed** — under discussion. - **Accepted** — current truth. - **Deprecated** — no longer recommended. - **Superseded by ADR-MMMM** — explicitly replaced; the new ADR references back. ## Related - [[Layered Memory Architecture]] - [[Context Compaction]] - [[AGENTS.md Convention File]] - [[Documenting Architecture Decisions (Nygard)]]