📄 Article
✓ Link checked
Free
Advanced
The original essay that introduced Architecture Decision Records, a one page format capturing the context, the decision, and its consequences. Asking your engineer to write a short ADR for a contested stack choice is the fairest test in your short answer: if they cannot state the tradeoff in terms of your goals, the record makes that obvious. It turns 'trust me' into a written, revisitable rationale.
Documenting Architecture Decisions
From Cognitect (Michael Nygard) by Michael Nygard 8 min read
- A decision record forces the tradeoff and consequences to be stated in writing.
- If the rationale cannot be written in a paragraph, the choice is not yet understood.
- Recorded decisions let a future team see why, not just what, was chosen.
