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 Records (ADR)
Also known as: adr, architecture-decision-record, decision-log, architecture-decisions
Intent
Capture significant architectural decisions with context, alternatives, and consequences — creating 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 team making architectural decisions
- •Team growing beyond tribal knowledge
- •Regulatory/audit requirements
- •Onboarding new members takes too long
✗ When Not to Use
- •Solo developer (personal notes sufficient)
- •Team with perfect memory and zero turnover
- •Decisions already in RFCs/design docs
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
- −Stored in wiki instead of repo (loses version history)
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
- architecture-doc
Related Patterns
- design-record
- tradeoff-analysis
- c4-modelling
- rfc
- decision-log
Competency Domains
decision makingeconomics evolutiondistribution communicationreliability opsdeployment