Architecture Decision Records (ADRs)
Lightweight documentation format for recording architectural decisions and their context.
An Architecture Decision Record (ADR) is a document that captures an important [[Architecture Decision (AD)]] made along with its context and consequences.
Structure
A typical ADR includes:
- Title: Short description of the decision
- Status: Proposed, accepted, deprecated, superseded
- Context: What forces are at play
- Decision: What we decided to do
- Consequences: What becomes easier or harder
Purpose
ADRs help:
- Document why decisions were made
- Preserve context for future team members
- Enable better decision-making over time
- Create institutional memory
- Avoid revisiting settled decisions
Related Concepts
- [[Architecture Decision Log (ADL)]] — the collection of ADRs for a project or organization
- [[Architecture Decision (AD)]] — the decisions that ADRs document
- [[Architecturally-significant Requirement (ASR)]]
- [[Engineering Strategy]]
- [[A Note on Distributed Computing]]
- Software architecture
- Technical documentation
References
- Architecture Decision Record (GitHub) — comprehensive guide and examples