Decisions
Architecture Decision Records (ADRs)
ADRs capture significant architectural decisions along with their context and consequences.
Why ADRs?
“Architecture is the decisions you wish you could get right early.” — Ralph Johnson
ADRs help us:
- Remember why decisions were made (especially months later)
- Onboard new team members with historical context
- Avoid revisiting the same debates repeatedly
- Learn from past trade-offs
What to Record
⚠️ Not everything needs an ADR. Focus on decisions that are:
- Hard to reverse
- Have significant impact
- Were contentious or non-obvious
Examples:
- Choosing a framework or major library
- Defining API conventions
- Selecting deployment strategies
- Establishing security policies
ADR Lifecycle
Proposed → Accepted → (Superseded | Deprecated)
| Status | Meaning |
|---|---|
| Proposed | Under discussion, not yet decided |
| Accepted | Decision is in effect |
| Superseded | Replaced by a newer ADR |
| Deprecated | No longer relevant |
Browse ADRs
See all decisions in the ADRs section.