Architecture Decision Records (ADR): The Team's Long-Term Technical Memory
Architecture Decision Records (ADR): The Team's Long-Term Technical Memory
Table of Contents
- The "Why Did We Do This?" Problem
- What an ADR Is (and Isn't)
- The Michael Nygard ADR Template: Full Breakdown
- Writing Effective Context Sections
- Writing Effective Consequences Sections
- The MADR Format: A Modern Alternative
- Git-Based ADR Governance Workflow
- Integrating ADRs with Backstage
- Which Decisions Warrant an ADR?
- ADR Status Lifecycle: Proposed → Accepted → Superseded
- Building an ADR Culture
- Frequently Asked Questions
- Key Takeaway
The "Why Did We Do This?" Problem
Every long-lived codebase accumulates decisions that become mysteries:
The cost of missing ADRs:
- New developers spend weeks reverse-engineering decisions before touching sensitive code
- "Safe" refactoring is impossible when rationale is unknown — you might break an implicit constraint
- The same architectural debate is re-litigated in every sprint retro ("why don't we just use GraphQL?")
- Onboarding time for senior engineers is measured in months, not days
An ADR written at the time the decision was made would have answered all these questions in 2 minutes.
What an ADR Is (and Isn't)
An ADR is:
- A short, specific record of one architectural decision (~1 page in Markdown)
- Immutable once accepted — you never edit an accepted ADR; you write a new one that supersedes it
- Focused on the "Why" — the "What" is visible in the code; the "Why" is only in the ADR
An ADR is NOT:
- A design document (those describe a system, not a decision)
- A retrospective (ADRs are written before or during implementation, not after)
- A technical specification (RFCs and specs describe how to build something)
- A ticket or story (those are transient; ADRs are permanent)
The Michael Nygard ADR Template: Full Breakdown
Michael Nygard's 2011 template is the industry standard — five sections that capture everything needed:
Writing Effective Context Sections
The Context is the most important section — it captures information that will be lost when the decision-makers leave. An effective Context includes:
1. The force driving the decision (why now?)
2. Hard constraints (business, technical, legal)
3. Options evaluated (not just the one chosen)
The MADR Format: A Modern Alternative
MADR (Markdown Any Decision Record) provides a more structured format ideal for teams that want explicit decision rationale and alternatives:
Git-Based ADR Governance Workflow
The most effective ADR workflow keeps records in the repository, alongside the code they describe:
The PR-based review workflow:
Which Decisions Warrant an ADR?
Write an ADR when:
- The decision is difficult to reverse (database choice, runtime language, major framework)
- The decision has non-obvious trade-offs (why async instead of sync, why eventual consistency)
- The decision will cause questions ("why don't we just use X?")
- The decision involves rejected alternatives that seem superior at first glance
- The decision has external constraints that future engineers won't know about
Don't write an ADR for:
- Trivial implementation choices (variable naming, folder structure)
- Decisions that are obvious from the code context
- Temporary decisions that will be revisited imminently
- Choices with no meaningful alternatives
Frequently Asked Questions
How do I get my team to actually write ADRs?
Start with requirements rather than requests: require an ADR for any decision that changes a dependency in package.json, go.mod, pom.xml, or requirements.txt. Add an ADR checklist item to your PR template for architectural changes. Have the tech lead write the first 5 ADRs as examples — teams model behaviour they see in leadership. Make ADR review part of your architecture review process, not an optional add-on.
How do ADRs differ from RFCs? RFCs (Request for Comments) are broader proposals for how to build something — they describe a design in detail and seek implementation feedback. ADRs capture a specific decision — they are more concise and focused on the "Why" rather than the "How". Many teams use both: an RFC to design a system, then an ADR to record the key decisions made during RFC review. GitHub uses both extensively.
Key Takeaway
Architecture Decision Records are the cheapest documentation investment with the highest return. One page of Markdown written in the 30 minutes after a decision is made prevents hours of archaeology, months of "why did we do this" uncertainty, and years of "nobody changes it because nobody understands it" stagnation. The practice is simple: every time a consequential architectural decision is made, write a short ADR with Context, Decision, and Consequences, and merge it to the repository via PR. The first ADR takes 45 minutes. The hundredth takes 10 minutes. The ROI compounds with every engineer who joins and every decision that is reconsidered.
Read next: Platform Engineering Architecture: The Internal Developer Platform →
Part of the Software Architecture Hub — comprehensive guides from architectural foundations to advanced distributed systems patterns.