ADR Template & Best Practices
Architecture Diagram
What Is an ADR?
An Architecture Decision Record (ADR) is a short document that captures a single architectural decision and the reasoning behind it. Michael Nygard first popularized the format, and it boils down to three questions: What did we decide? Why? And what happens because of it?
ADRs are intentionally small compared to design docs or RFCs. Each one covers exactly one decision. That granularity makes them easy to search, link together, and keep up to date as the system evolves over months and years.
The Template
Here is a five-section template that holds up well in practice:
- Title: A short noun phrase. Something like "Use PostgreSQL for transactional data storage."
- Status: One of Proposed, Accepted, Deprecated, or Superseded by ADR-NNN.
- Context: The forces at play. Business requirements, technical constraints, team capabilities, timeline pressure. Be honest about what you did not know.
- Decision: The choice you made, stated in active voice. Write "We will use X," not "X was chosen."
- Consequences: Both the good and the bad. What gets easier? What gets harder? What new constraints does this create?
When to Write One
Write an ADR when the decision is significant and hard to reverse. Good triggers: choosing a database, adopting a new framework, changing an API contract, picking a deployment strategy, deciding on a data partitioning scheme. You do not need one for every library choice or code style preference.
Getting Buy-In
The best ADRs are written before implementation starts. Share it as a pull request and ask for review from the engineers who will have to live with the consequences. Keep the review window short, two to three business days, with a clear deadline. Silence after the deadline counts as consent.
The Immutability Principle
Once an ADR is accepted, do not go back and edit it to reflect new information. Instead, write a new ADR with status "Supersedes ADR-NNN" and explain what changed. This preserves the historical record and makes it possible to trace how your architecture evolved. Think of your ADR log like an append-only event store.
Building a Decision Graph
Number your ADRs sequentially (ADR-001, ADR-002, and so on) and cross-reference them. Over time you end up with a navigable graph of decisions. When you onboard new engineers, the ADR log becomes a guided tour of why the system looks the way it does. Teams that keep their ADR logs current report 40-60% faster onboarding for senior engineers joining the team.
Key Points
- •ADRs capture the context, decision, and consequences of significant architectural choices so that future reasoning stays transparent
- •Keep ADRs immutable once accepted. If a decision gets superseded, create a new ADR that references the original
- •Store ADRs in the repository alongside the code they affect. Decisions should live where the code lives
- •Include a Status field (Proposed, Accepted, Deprecated, Superseded) to track the lifecycle of each decision
- •Link related ADRs together to form a decision graph. Individual decisions rarely exist in isolation
Common Mistakes
- ✗Writing ADRs after the fact with revisionist context. Capture the decision when it is made, including the uncertainty you felt at the time
- ✗Making ADRs too long and detailed. A good ADR is 1-2 pages, not a design document
- ✗Not recording rejected alternatives. The 'why not' is often more valuable than the 'why'
- ✗Treating ADRs as bureaucratic overhead instead of team knowledge. If nobody reads them, your template is too heavy