Architecture Decision Records (ADRs)

Also Known As

TL;DR

Explanation

An ADR records: the architectural decision made, the context that made it necessary, the options considered, the rationale for the choice, and the consequences. Stored as version-controlled Markdown files alongside code (docs/adr/), they are accessible, searchable, and historically accurate. ADRs prevent the constant re-arguing of settled decisions and help onboard new developers who wonder 'why did they do it this way?'.

Diagram

flowchart TD
    PROBLEM[Architectural decision needed] --> ADR[Create ADR document]
    ADR --> SECTIONS[Sections:<br/>Title + date + status<br/>Context - why decide now<br/>Decision - what we chose<br/>Consequences - trade-offs]
    SECTIONS --> STATUS{Status}
    STATUS -->|Proposed| REVIEW[Team reviews]
    REVIEW -->|Accepted| ACCEPTED[ADR accepted<br/>committed to repo]
    REVIEW -->|Rejected| REJECT[ADR rejected<br/>record why]
    ACCEPTED -->|Better info| SUPERSEDED[Superseded by ADR-N+1]
    subgraph Benefits
        HIST2[Why decisions were made<br/>visible to future devs]
        ONBOARD[Onboarding reference<br/>no tribal knowledge]
    end
style ACCEPTED fill:#238636,color:#fff
style REJECT fill:#f85149,color:#fff
style SUPERSEDED fill:#d29922,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Writing ADRs after the fact without the original context — the rationale is reconstructed and loses authenticity.
• Not recording rejected alternatives — often the most valuable part is understanding what was considered and why it was rejected.
• ADRs that are too long — keep them to one page maximum; detail belongs in linked documentation.
• Not treating ADRs as immutable — an ADR records a decision at a point in time; supersede it with a new ADR rather than editing.

Code Examples

# No ADR — new developer asks why the system uses Redis for sessions:
# 'I don't know, it was here when I joined'
# 'Let's switch to database sessions, it's simpler'
# Team spends 2 hours re-arguing a decision made 3 years ago
# No one remembers the PHP-FPM sticky session issue that drove the original choice

# docs/adr/0003-redis-for-session-storage.md
# Status: Accepted | Date: 2023-01-15
# Context: PHP-FPM pool has 20 workers across 3 servers; sticky sessions cause uneven load.
# Decision: Use Redis for centralized session storage.
# Alternatives considered: DB sessions (slower), filesystem (not multi-server).
# Consequences: Adds Redis dependency; sessions survive server restarts.

References

• ↗ https://adr.github.io/
• ↗ https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

Tags

Related Terms