Core Idea
Architecture Decision Records (ADRs) follow a four-part format: Status, Context, Decision, and Consequences—creating a lightweight template that captures why decisions were made and their expected impact.
ADR Format and Structure
ADRs use a consistent structure designed to answer three critical questions: What situation prompted this decision? What did we decide and why? What are the results? This minimal format balances documentation completeness against the cost of creating and maintaining records.
Four-Part Structure:
1. Status Field: Tracks the decision lifecycle through states: Proposed, Accepted, Deprecated, or Superseded. Superseded status links to the ADR that replaced it, creating a traceable decision history.
2. Context Section: Captures the forces at play when the decision was made—business constraints, technical limitations, architecture characteristics driving the need. Without context, decisions appear arbitrary and cannot be re-evaluated when those forces change.
3. Decision Section: States what was chosen and the reasoning. Not just “We chose MongoDB” but “We chose MongoDB because our primary characteristic is elasticity, our data model is document-oriented, and we need horizontal scaling.” The reasoning makes the decision defensible and evaluable.
4. Consequences Section: Documents both positive and negative outcomes. Every decision involves trade-offs. Recording that “This improves performance but increases operational complexity” prevents future confusion about whether that complexity was intentional or accidental.
This four-part structure provides just enough rigor to prevent Architecture-Decision-Anti-Patterns like Groundhog-Day-Anti-Pattern (re-debating decisions) and Email-Driven-Architecture-Anti-Pattern (losing decision rationale), while remaining lightweight enough that architects actually use it.
Why This Matters
Without a standard ADR format, teams either don’t document decisions at all or create inconsistent records that are hard to search and compare. The format’s simplicity removes excuses for not documenting architecturally significant choices. The consequences section creates institutional memory about intentional trade-offs versus defects.
Related Concepts
- Architecture-Decision-Records
- Architecturally-Significant-Decisions
- Architecture-Decision-Anti-Patterns
- Architectural-Governance
- Groundhog-Day-Anti-Pattern
- Email-Driven-Architecture-Anti-Pattern
- Fundamentals of Software Architecture - Richards & Ford - 2020
Sources
- Richards, Mark and Neal Ford (2020). Fundamentals of Software Architecture: An Engineering Approach. O’Reilly Media. ISBN: 978-1-492-04345-4. Chapter 19: Architecture Decisions. Available: https://www.oreilly.com/library/view/fundamentals-of-software/9781492043447/
Note
This content was drafted with assistance from AI tools for research, organization, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.