Architecture Decision Records (ADRs)
debt(d8/e5/b5/t3)
Closest to 'silent in production until users hit it' (d9), -1. The absence of ADRs is not caught by any compiler, linter, or SAST tool. The listed tools (adr-tools, mkdocs, docusaurus) are documentation generators, not automated detectors of missing decisions. The absence is only noticed during onboarding or refactoring discussions when context is lost — essentially a social/process gap. Scored d8 rather than d9 because a deliberate team process check (e.g., PR template asking 'does this need an ADR?') can surface it, though this is manual.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix suggests creating a markdown file per decision, which sounds like e1 for a single ADR. However, the real remediation cost is retroactively documenting existing undocumented decisions across the system — reconstructing context that may be partially lost (as noted in common_mistakes about writing ADRs after the fact). This requires interviewing team members, reviewing git history, and producing multiple documents. This is a significant effort across the project's documentation, fitting e5.
Closest to 'persistent productivity tax' (b5). ADRs apply across web and CLI contexts and affect every architectural discussion going forward. Once adopted, maintaining the discipline of writing ADRs for every significant decision is a persistent process tax on the team. Not doing them creates ongoing burden via re-litigation of past decisions. The practice doesn't define the system's shape (not b7+), but it does create a persistent workflow obligation that affects many work streams.
Closest to 'minor surprise' (t3). The misconception field states that developers believe ADRs are only for large organisations, when they're valuable for teams of 2+ or even solo developers. This is a modest misconception — a competent developer hearing 'Architecture Decision Records' would generally understand the concept correctly (document why you made a choice), but might wrongly dismiss it as enterprise overhead. The common mistakes (editing instead of superseding, not recording rejected alternatives) are minor surprises rather than serious traps.
Also Known As
TL;DR
Explanation
An ADR records: the architectural decision made, the context that made it necessary, the options considered, the rationale for the choice, and the consequences. Stored as version-controlled Markdown files alongside code (docs/adr/), they are accessible, searchable, and historically accurate. ADRs prevent the constant re-arguing of settled decisions and help onboard new developers who wonder 'why did they do it this way?'.
Diagram
flowchart TD
PROBLEM[Architectural decision needed] --> ADR[Create ADR document]
ADR --> SECTIONS[Sections:<br/>Title + date + status<br/>Context - why decide now<br/>Decision - what we chose<br/>Consequences - trade-offs]
SECTIONS --> STATUS{Status}
STATUS -->|Proposed| REVIEW[Team reviews]
REVIEW -->|Accepted| ACCEPTED[ADR accepted<br/>committed to repo]
REVIEW -->|Rejected| REJECT[ADR rejected<br/>record why]
ACCEPTED -->|Better info| SUPERSEDED[Superseded by ADR-N+1]
subgraph Benefits
HIST2[Why decisions were made<br/>visible to future devs]
ONBOARD[Onboarding reference<br/>no tribal knowledge]
end
style ACCEPTED fill:#238636,color:#fff
style REJECT fill:#f85149,color:#fff
style SUPERSEDED fill:#d29922,color:#fff
Common Misconception
Why It Matters
Common Mistakes
- Writing ADRs after the fact without the original context — the rationale is reconstructed and loses authenticity.
- Not recording rejected alternatives — often the most valuable part is understanding what was considered and why it was rejected.
- ADRs that are too long — keep them to one page maximum; detail belongs in linked documentation.
- Not treating ADRs as immutable — an ADR records a decision at a point in time; supersede it with a new ADR rather than editing.
Code Examples
# No ADR — new developer asks why the system uses Redis for sessions:
# 'I don't know, it was here when I joined'
# 'Let's switch to database sessions, it's simpler'
# Team spends 2 hours re-arguing a decision made 3 years ago
# No one remembers the PHP-FPM sticky session issue that drove the original choice# docs/adr/0003-redis-for-session-storage.md
# Status: Accepted | Date: 2023-01-15
# Context: PHP-FPM pool has 20 workers across 3 servers; sticky sessions cause uneven load.
# Decision: Use Redis for centralized session storage.
# Alternatives considered: DB sessions (slower), filesystem (not multi-server).
# Consequences: Adds Redis dependency; sessions survive server restarts.