Problem
Architectural decisions are made in meetings, Slack, or heads — then forgotten. New team members don't know why. Decisions get revisited without context.
decision-makingestablished · low operational burden
Architecture Decision Record (ADR)
Also known as: architecture decision record, decision log
Intent
Capture a significant architectural decision with its context, alternatives considered, and consequences — creating a searchable, reviewable decision history.
Forces
- •Decisions must be findable and understandable months later
- •Context at decision time is different from context at review time
- •Lightweight enough to actually write
- •Must capture rejected alternatives to prevent re-litigation
Solution
✓ When to Use
- •Any decision expensive to reverse (data model, protocol, cloud provider, framework)
- •Decisions affecting multiple teams or services
- •When you'd want to explain 'why' to a new hire in 6 months
✗ When Not to Use
- •Tactical coding decisions (variable names, library versions)
- •Decisions already captured in RFCs or design docs
- •Reversible configuration choices
Pros
- +Creates organisational memory
- +Forces explicit trade-off analysis
- +Enables decision review and supersession
- +Lightweight — 5-15 minutes to write
Cons
- −Requires discipline to maintain
- −Can become bureaucratic if over-applied
- −Superseded ADRs need clear linking
Cost Profile
Infrastructure
None — markdown files in repo
Operational
Low — review in PR process
Cognitive
Low — structured template
Failure Modes
Written after the fact with post-hoc justification
Only one option listed (not a decision)
Superseded without linking to replacement
Stored in wiki instead of repo (loses version history)
Real-World Examples
Alternatives
- rfc
- design-doc
- decision-log
Related Patterns
- design-record
- tradeoff-analysis
- c4-modelling
Competency Domains
requirements constraintseconomics evolution