Architecture Decision Records (ADR) in Practice: From Blank Page to Traceable Architecture Evolution
ADR (Architecture Decision Record) is a lightweight method for recording architecture decisions, answering "why was it designed this way." This article covers the ADR format, when to write them, and how to manage them — with a ready-to-use template and team adoption tips for teams adopting or considering ADRs.
The Bottom Line: ADRs Are Letters to Your Future Self
Every team has encountered this: six months later, looking at your own code, wondering why a particular approach was chosen. The code does not reveal the decision context. The PR description only says “changed to X,” but nobody remembers why Y was not chosen.
ADR (Architecture Decision Record) solves this problem — it uses lightweight Markdown files to record the context, alternatives, and final choice of each architecture decision.
1. ADR Format
Recommended Template
# [Number]. [Title]
Date: [YYYY-MM-DD]
## Status
[Proposed | Accepted | Deprecated | Superseded]
## Context
[Describe the background for the decision. Why is this decision necessary? What problem does the current system have?]
## Decision
[What we decided to do. Use declarative sentences, not "consider" or "maybe"]
## Alternatives
- [Option A]: [Pros and cons]
- [Option B]: [Pros and cons]
- [Option C]: [Pros and cons]
## Consequences
[Positive and negative impacts of this decision. Includes technical debt, migration cost, learning curve, etc.]
## Compatibility
[Does this decision affect existing systems? Is migration needed? Is there a compatibility period?]Example
# 1. Use PostgreSQL as Primary Database
Date: 2026-07-16
## Status
Accepted
## Context
We need to choose a primary database for the new Token trading platform. Requirements include: ACID transaction support, JSON field storage, complex queries and reporting. The team is familiar with SQL.
## Decision
Use PostgreSQL 16 as the primary database.
## Alternatives
- MySQL 8.0: ACID support is mature, but JSON query capabilities are weaker than PostgreSQL, and it lacks window functions for advanced analytics
- MongoDB 7.0: NoSQL flexibility, but does not support cross-document transactions (problematic for strong consistency scenarios)
- TimescaleDB: Excellent for time-series, but not mature enough as a general-purpose primary database
## Consequences
Positive: team does not need to learn a new query language; PostgreSQL's JSON and window functions meet Token platform requirements
Negative: compared to MySQL, PostgreSQL's ops toolchain is slightly weaker, requiring additional monitoring and backup configuration
## Compatibility
New system, no historical data migration issues2. When to Write ADRs
Scenarios Requiring ADRs
- Introducing a new technology stack or framework
- Changing inter-module communication patterns (REST → message queue)
- Choosing a data storage solution (PostgreSQL vs MongoDB)
- Determining deployment strategy (Docker Compose vs K8s)
- Changing system security strategy (authentication method, permission model)
Scenarios Not Requiring ADRs
- Routine bug fixes
- Small-scale refactoring (renaming, extracting common methods)
- Repeated decisions already covered by existing ADRs
3. ADR Management
Directory Structure
docs/adr/
README.md # ADR index
0001-use-postgresql.md
0002-use-docker-compose.md
0003-use-jwt-auth.mdIndex File Example
# Architecture Decision Records
| # | Title | Status | Date |
|---|-------|--------|------|
| 1 | Use PostgreSQL as primary database | Accepted | 2026-07-16 |
| 2 | Use Docker Compose for deployment | Accepted | 2026-07-17 |
| 3 | Use JWT authentication | Superseded → 4 | 2026-07-18 |
| 4 | Use Session + Redis authentication | Accepted | 2026-07-20 |Lifecycle
Proposed → Accepted → Deprecated
→ Superseded → (new ADR)Summary
| Layer | Key Principle | Common Mistake |
|---|---|---|
| Content | Record decisions, not implementation | Writing as technical documentation |
| Timing | Write when deciding, not retroactively | Writing months later with inaccurate memory |
| Location | With code, submitted with PR | Stored in Wiki or shared docs, unmaintained |
| Management | Maintain index, status, decision chain | Written once, never updated |
The value of ADRs is not “how many you wrote” — it is “six months later, you can still understand why you chose that path.” A well-maintained ADR repository reflects the true evolution of your system better than any architecture document.
Need architecture review or technical consulting? Contact us — tell us about your system and decision needs, feasibility within 24 hours.
Related reading
- How to Run a Technical Review — upstream technical decision-making for ADRs
- Microservice Decomposition — ADR practice in architecture evolution
FAQ
What is the difference between an ADR and regular technical documentation?
ADRs record decisions, not implementation details. Technical documentation describes "how the system works"; ADRs describe "why it was built this way." The difference: implementation details become outdated as code changes, but decision rationale (context, alternatives, trade-offs) rarely goes out of date. ADRs are letters to your future self — six months later, an ADR tells you why you chose A over B.
When should an ADR be written?
Write an ADR when you make an architecture decision — not after the fact. What counts as an "architecture decision"? ① Introducing a new technology stack or framework; ② Changing communication patterns between modules (e.g., REST to message queue); ③ Choosing a data storage solution (PostgreSQL vs MongoDB); ④ Determining deployment strategy (Docker Compose vs K8s). Small decisions (e.g., which algorithm to use in a function) do not need ADRs.
Where should ADRs be stored?
Store them with the codebase in Markdown format under docs/adr/, with filenames like NNNN-title-with-dashes.md. Version control them alongside the code, submitted with the PR. This way, ADRs map one-to-one with code changes, and git blame traces back to the specific decision and modification.
How do you manage a growing collection of ADRs?
Maintain an ADR index (README.md) listing all ADRs by number, title, status, and date. Categorize by status: Proposed, Accepted, Deprecated, Superseded. Superseded ADRs use a Superseded-by field pointing to the new ADR, forming a decision chain.
This article comes from AI Enable Harness front-line delivery practice. Need a similar system or optimization service?
Subscribe to Updates
Get notified when new articles are published. No spam, occasional updates only.
Subscribe →