Manu's Vault

Architecture Decision Records

8 min readStatus:Seedling

Core Idea

Architecture Decision Records (ADRs) document significant architectural decisions along with their context, rationale, and trade-offs. Unlike traditional documentation, ADRs capture the “why” and enable knowledge flow through time, helping future developers understand not just what was decided but why alternatives were rejected.

What Are ADRs?

Architecture Decision Record:

  • Short document (1-2 pages) capturing a single architecturally significant decision
  • Immutable once written (new decisions get new ADRs)
  • Numbered sequentially (ADR-001, ADR-002, etc.)
  • Stored in version control with the code
  • Written at the time the decision is made

Architecturally Significant Decisions (Richards & Ford): Not every decision needs an ADR. Only capture decisions that:

  • Affect the structure, characteristics, or dependencies of the system
  • Are difficult or costly to reverse
  • Have long-term impact on the system
  • Require understanding by future developers

Key Elements (Basic Structure from Richards & Ford):

  1. Title: Short, descriptive name of the decision
  2. Status: Proposed | Accepted | Deprecated | Superseded
  3. Context: What situation prompted this decision? What forces are at play?
  4. Decision: What we decided to do and why
  5. Consequences: What are the results? (Both positive and negative)

Why ADRs Matter for Knowledge Flow

Traditional Documentation Problem:

  • Documents what exists
  • Doesn’t explain why
  • Gets outdated quickly
  • Future developers don’t understand reasoning
  • “We’ve always done it this way”

ADRs Enable Knowledge Flow Through Time:

  • Future developers understand past decisions
  • Can evaluate if context has changed
  • Know what alternatives were considered
  • Understand trade-offs accepted
  • Can make informed changes when needed

The “Why” is More Important Than “What”

Without ADRs:

Code: "We use event sourcing for the order system"
Developer: "Why? Should I use it for the customer system too?"
Answer: Unknown, ask around, maybe no one remembers

With ADRs:

ADR-015: "Use Event Sourcing for Order System"

Context: Orders have complex audit requirements.
Need to replay state changes.

Decision: Event sourcing for orders only

Rationale: Audit requirements justify complexity.
Customer system doesn't need this.

Consequences: More complex but meets compliance needs.
Don't apply to other bounded contexts without similar needs.

ADR Template Example

# ADR-023: Use PostgreSQL for User Profile Storage
 
## Status
Accepted
 
## Context
We need to store user profile data with:
- ACID guarantees for consistency
- Relational queries for reporting
- Moderate write volume (1000s/sec, not millions)
- Strong community support
- Team has SQL experience
 
## Decision
Use PostgreSQL 15+ as the primary database for user profiles.
 
## Alternatives Considered
1. MongoDB - Better for high write volume, but we don't need it
2. MySQL - Similar features, but PostgreSQL has better JSON support
3. DynamoDB - Would require team to learn new paradigm
 
## Consequences
**Positive:**
- Leverages team's existing SQL knowledge
- JSON columns give us flexibility where needed
- Strong consistency guarantees
- Mature ecosystem
 
**Negative:**
- Vertical scaling limits (but not a concern at our scale)
- More operational overhead than managed NoSQL
- Need to manage schema migrations carefully
 
## Notes
Re-evaluate if write volume exceeds 10K/sec or
if team composition changes significantly.

How ADRs Enable Knowledge Flow

1. Flow Through Time:

  • Decisions today inform developers tomorrow
  • Context preserved even when people leave
  • Institutional memory captured

2. Flow Through Team:

  • Everyone can read why decisions were made
  • New team members get up to speed faster
  • Shared understanding develops

3. Flow Through Discussion:

  • Writing an ADR forces clear thinking
  • Team discusses before accepting
  • Better decisions through collaboration

4. Flow Through Reversal:

  • When context changes, easy to see why decision was made
  • Can create new ADR superseding old one
  • Evolution of thinking is visible

ADRs vs Other Documentation

README:

  • What the project is
  • How to get started
  • Current state

Architecture Diagrams:

  • What the structure looks like
  • How components relate
  • Current state

ADRs:

  • Why the structure exists
  • What alternatives were rejected
  • Historical reasoning
  • Decision trail over time

All three are needed. ADRs complement, don’t replace.

When to Write an ADR

Write an ADR when:

  • The decision will be hard to reverse
  • Future developers will wonder “why?”
  • Multiple viable alternatives exist
  • The decision affects multiple teams
  • There are significant trade-offs

Don’t write an ADR for:

  • Trivial decisions easily reversed
  • Obvious choices with no alternatives
  • Implementation details (which library version)
  • Decisions that will change frequently

Architecture Decision Anti-Patterns (Richards & Ford)

1. Covering Your Assets Anti-Pattern:

  • Making decisions without clear justification
  • Documenting vaguely so you can blame others later
  • “It’s the best practice” without explaining why
  • Impact: Team doesn’t understand reasoning, can’t adapt
  • Solution: Be explicit about context and trade-offs in ADR

2. Groundhog Day Anti-Pattern:

  • Repeatedly debating the same architectural decisions
  • No formal record, so debates resurface every few months
  • “Didn’t we already discuss this?” syndrome
  • Impact: Wasted time, team frustration, inconsistent decisions
  • Solution: Document decisions in ADRs to prevent re-litigation

3. Email-Driven Architecture Anti-Pattern:

  • Making significant decisions in email threads
  • Context scattered, hard to find later
  • Only subset of team sees the reasoning
  • Impact: Lost institutional knowledge, hidden decisions
  • Solution: Use ADRs as single source of truth, reference in emails

Common ADR Implementation Anti-Patterns

4. Retroactive ADRs:

  • Writing ADRs long after decisions made
  • Context and reasoning already lost
  • Better than nothing, but far less valuable

5. ADR Novels:

  • 10-page documents no one reads
  • Keep to 1-2 pages max
  • Link to detailed docs if needed

6. Never Revisiting:

  • Old ADRs remain “accepted” forever
  • Context changes but decisions don’t evolve
  • Mark as “superseded” or “deprecated” when updated

7. No Consequences Section:

  • Only documenting the decision
  • Not thinking through what becomes harder
  • Consequences force honest evaluation of trade-offs

ADRs and Fitness Functions (Richards & Ford)

Fitness Functions are automated tests that verify architectural characteristics remain healthy as systems evolve. ADRs and fitness functions work together:

ADR Documents the Decision:

  • “We use layered architecture with strict layer isolation”
  • “No presentation layer may directly call the database”

Fitness Function Enforces It:

def test_layer_isolation():
    """Ensure presentation layer doesn't call data layer"""
    violations = find_dependencies(
        from_package="presentation",
        to_package="data"
    )
    assert len(violations) == 0, f"Layer violations: {violations}"

Connection:

  • ADR explains “why” (knowledge flow through time)
  • Fitness function enforces “what” (automated governance)
  • Together: Documented reasoning + automated enforcement
  • Prevents architectural drift without manual review

See Chapter 6 of Richards & Ford for detailed coverage of fitness functions.

ADRs and Knowledge Stock vs Flow

ADRs are knowledge stock that enables flow:

Stock Component:

  • Written records of decisions
  • Stored in repository
  • Searchable and discoverable

Flow Component:

  • Enable understanding without asking people
  • Allow evaluation of changing context
  • Support async knowledge transfer
  • Create shared understanding

This is the ideal: high stock that enables high flow.

Using ADRs for Standards (Richards & Ford)

ADRs aren’t just for one-time decisions—they can establish ongoing standards:

Example: Logging Standard

  • ADR documents: “All services must log at INFO level or higher”
  • Context: Need centralized monitoring and debugging
  • Decision: Standardize on structured JSON logging
  • Consequences: Easier to aggregate logs, but more boilerplate

Benefits of Standards as ADRs:

  • Standards have clear rationale (not arbitrary rules)
  • Team understands why standard exists
  • Can be challenged if context changes
  • Enforcement through fitness functions

Storing ADRs (Richards & Ford)

Recommended Approach:

  • Store in version control with the codebase
  • Common location: docs/adr/ or docs/architecture/decisions/
  • Format: Markdown for readability and diffing
  • Number sequentially: 0001-use-postgresql.md

Why Co-locate with Code:

  • ADRs evolve with the system
  • Version history shows decision timeline
  • Developers see ADRs during code review
  • No separate documentation system to maintain

Alternative: Wiki/Confluence

  • Can work, but loses version history integration
  • Risk of documentation drift from code
  • Prefer: Keep ADRs in repo, link from wiki if needed

Practical Implementation

Getting Started:

  1. Create docs/adr/ directory in repository
  2. Start numbering from ADR-001 (or 0001)
  3. Use template for consistency
  4. Write one for your next significant decision
  5. Build the habit gradually

Tooling:

  • Plain markdown files in version control (Richards & Ford recommendation)
  • Tools exist (adr-tools, log4brains) but optional
  • Keep it simple: markdown + git = sufficient

Process:

  1. Propose ADR in pull request
  2. Team discusses (prevents Groundhog Day anti-pattern)
  3. Revise based on feedback
  4. Merge when accepted (status: Accepted)
  5. Implement the decision
  6. Enforce through fitness functions when possible

Connection to Architecture Role

The architect as facilitator uses ADRs as a key tool:

  • Makes architectural thinking visible
  • Enables team participation in decisions
  • Creates learning opportunities
  • Distributes architectural knowledge

ADRs transform architecture from “architect decides” to “team understands and decides together.”

Sources

Primary References:

  • Nygard, Michael (2011). “Documenting Architecture Decisions.” Cognitect Blog.

  • 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
    • Architecture Decision Anti-Patterns (Covering Your Assets, Groundhog Day, Email-Driven Architecture)
    • Architecturally Significant Decisions framework
    • ADR basic structure and format
    • Storing ADRs in version control
    • Using ADRs for standards
    • Connection to fitness functions (Chapter 6)
    • 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.

Graph View

Backlinks