## Core Insight Architecture Decision Records (ADRs) are short documents capturing single architectural decisions with context, rationale, and consequences. They serve dual purposes: historical record (explaining why systems are built as they are) and clarification tool (writing surfaces disagreements and forces resolution). ## Evidence 1. **Format**: Short documents (1-2 pages), one decision per file 2. **Immutable history**: Never modify; supersede with linked replacement 3. **Lifecycle**: proposed → accepted → superseded 4. **Origin**: Michael Nygard (2011), influenced by pattern languages and decision logs ## Structure | Section | Purpose | |---------|---------| | **Decision** | The decision itself | | **Rationale** | Problem, trade-offs, forces considered | | **Alternatives** | Serious options considered with pros/cons | | **Consequences** | Explicit implications | | **Confidence** | Degree of uncertainty | | **Reevaluation Triggers** | Context changes prompting review | ## Connections - **Validates**: [[Documentation as Thinking]] — writing surfaces and resolves disagreements - **Validates**: [[Immutable Documentation]] — append-only history preserves decision lineage - **Implements**: [[Advice Process]] — elicits expertise and drives alignment - **Parallel**: [[Decision Logs]] — organizational memory for "why" not just "what" - **Application**: For software teams: adopt ADRs for any non-trivial architectural choice. For personal projects: maintain decision log for future reference. - **Cross-Domain**: Engineering (design decisions), product (feature prioritization), business (strategy pivots) - **Writing style**: Inverted pyramid — most important material first, details at end ## Practical Implementation **Storage**: `doc/adr/` in source repository (or team website for ecosystem-wide decisions) **Naming**: `0001-HTMX-for-active-web-pages` (monotonic number + descriptive name) **Format**: Markdown for readability and diff-friendliness **Tools**: [adr-tools](https://github.com/npryce/adr-tools) — CLI for managing ADRs ## Key Constraints - Non-developers may struggle with git-based storage - Ecosystem-spanning decisions require location outside single codebase - Brevity paramount — link to supporting material rather than including it ## Source Martin Fowler: https://martinfowler.com/bliki/ArchitectureDecisionRecord.html (March 24, 2026) Original concept: Michael Nygard (2011) — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions