ADR Format and Structure

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

Purpose: Architecture Decision Records use a simple, 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 the records

Four-Part Structure:

1. Status Field:

• Tracks the decision lifecycle through states: Proposed, Accepted, Deprecated, or Superseded
• Allows teams to understand not just what was decided, but the current validity of that decision
• Superseded status: Links to the ADR that replaced it, creating a traceable decision history
• Proposed status: Enables teams to document options under consideration before committing

2. Context Section:

• Captures the forces at play when the decision was made:
  • What business constraints existed?
  • What technical limitations?
  • What architecture characteristics drove the need?
• Purpose: Prevents future teams from asking “Why did they do it this way?”
• Enables re-evaluation when those forces change
• Without context: Decisions appear arbitrary

3. Decision Section:

• States what was chosen and the reasoning
• Not just: “We chose MongoDB”
• Instead: “We chose MongoDB because our primary characteristic is elasticity, our data model is document-oriented with minimal relations, 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
• Example: Recording that “This improves performance but increases operational complexity” prevents future confusion about whether that complexity was intentional or accidental
• Purpose: Where you acknowledge what you’re accepting as the cost of the decision

Balance: This four-part structure provides just enough rigor to:

• Prevent Architecture-Decision-Anti-Patterns like:
  • Groundhog-Day-Anti-Pattern (re-debating decisions)
  • 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. Its consistency means new team members can quickly find and understand past decisions. 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

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.