Architecture Decision Record
Document significant technical decisions with context and trade-offs.
An Architecture Decision Record (ADR) documents a significant technical decision: context, options, decision, consequences. It preserves why for future teams.
Without ADRs, reversals repeat debates. Onboarding slows. Compliance audits lack trail.
At irreversible forks — data store, auth model, monolith vs services, vendor selection.
- Title and status (proposed/accepted/deprecated).
- Context and forces.
- Options considered.
- Decision and rationale.
- Consequences positive/negative.
- Link to tech canvas and risks.
- Dated and owned.
- Options fair, not strawmen.
- Consequences include ops impact.
- ADRs after the fact only.
- No deprecation when reversing.
- Too granular — decision not significant.
Northvale Systems ADR-007: adopt managed OCR API vs on-prem — chose API with PII redaction pipeline; reverses if vendor exits region.
PulseWell ADR: choose warehouse vs stream for analytics — chose warehouse for auditability; noted 24h latency consequence.
Harbor Consulting ADR: off-the-shelf LMS for training videos vs custom — chose LMS for speed; branded subdomain consequence accepted.
Clearwater Initiative ADR-003: SMS vs USSD for alerts — chose SMS for readability; revisit if telco costs spike.
/tech adr-document, IDs ADR-01. Linked from tech solution canvas.
Related techniques
Sources & further reading
- Nygard, M. (2011). Documenting architecture decisions. Cognitect blog.