Architecture Decision Records: Documentation That Gets Read
ADRs are the only documentation I've seen engineers voluntarily read. Use a template and review process to capture decisions, alternatives and consequences.
I've written wikis that nobody opened. I've created Confluence spaces that became digital graveyards within weeks. I've maintained README files that drifted so far from reality they became actively harmful. Then I discovered Architecture Decision Records, and something changed: engineers actually read them.
ADRs explain why the system was built this way, which alternatives were considered and which constraints shaped the decision. Read them within the systematic codebase understanding process.
Figure 1. Preserve the reasoning and make the current status clear.
An Architecture Decision Record is a short document that captures a single architectural decision, the context around it, the options considered, and the rationale for the choice made. That's it. One decision, one document, typically one to two pages.
Michael Nygard described this lightweight record format in 2011. His proposal covers architecturally significant decisions, with context, decision, status and consequences.[1]
Traditional documentation fails for three reasons:
It tries to describe the current state. The moment code changes, the documentation is wrong. Keeping docs synchronized with code is a losing battle. I've never seen a team win it at scale.
It lacks motivation. A wiki page that says "We use PostgreSQL for the primary database" tells you nothing useful. You can see that from the code. What you can't see from the code is why you chose PostgreSQL over DynamoDB, what constraints drove that choice, and under what circumstances you'd reconsider.
Nobody owns it. Documentation written by everyone is maintained by no one.
ADRs preserve the reasoning at the time of a decision. Keep accepted content as history, and update the status and replacement link when a new ADR supersedes it. Name the author and the reviewers so responsibility for the record is visible.[2]
Figure 2. Capture the constraints and rejected options as well as the decision.
I've iterated on this template across three companies. This version hits the sweet spot between thoroughness and brevity.
markdown
# ADR-{number}: {Title}**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-{number}**Date:** YYYY-MM-DD**Author:** Name**Reviewers:** Name, Name## ContextWhat is the situation that requires a decision? What problem are we solving?What constraints exist? (2-4 paragraphs)## DecisionWhat is the decision? State it clearly in one sentence, then elaborate.## Options Considered### Option A: {Name}- Pros: ...- Cons: ...- Estimated effort: ...### Option B: {Name}- Pros: ...- Cons: ...- Estimated effort: ...### Option C: {Name} (if applicable)- Pros: ...- Cons: ...- Estimated effort: ...## RationaleWhy did we choose this option? What were the deciding factors?What tradeoffs are we accepting? (2-3 paragraphs)## ConsequencesWhat are the positive and negative consequences of this decision?What will we need to do as a result? What doors does this close?## ReferencesLinks to relevant RFCs, blog posts, docs, or Slack threads.
Here's a slightly anonymized ADR from a real project:
markdown
# ADR-014: Use Event Sourcing for Order Management**Status:** Accepted**Date:** 2025-08-15**Author:** Vaibhav Verma**Reviewers:** Sarah Chen, Marcus Johnson## ContextOur order management system currently uses a CRUD model with asingle `orders` table. We've been asked to implement full orderhistory, audit logging, and the ability to replay past states fordispute resolution. Our current approach of adding columns like`previous_status` and `status_changed_at` is becoming unwieldy.We have 47 columns on the orders table, 12 of which are audit-related.We process approximately 15,000 orders per day. Order statetransitions average 4.2 per order. Our SLA requires 99.9% uptimefor order operations.## DecisionWe will implement event sourcing for the order aggregate.Order state will be derived from an append-only event log ratherthan stored as mutable rows.## Options Considered### Option A: Expand the CRUD Model- Pros: No architectural change, team already knows the pattern- Cons: Table continues to grow, audit queries become slower, no true state replay capability- Estimated effort: 2 weeks### Option B: Event Sourcing with Custom Implementation- Pros: Full control, tailored to our needs- Cons: Significant development effort, event store reliability is our responsibility- Estimated effort: 6-8 weeks### Option C: Event Sourcing with EventStoreDB- Pros: Purpose-built event store, built-in projections, proven at scale- Cons: New infrastructure dependency, team learning curve, operational overhead- Estimated effort: 4-5 weeks## RationaleWe chose Option C. The deciding factors were: (1) our team has noevent sourcing experience, so a purpose-built store reduces risk,(2) EventStoreDB's projection system handles our read-modelrequirements without custom code, (3) the 15,000 orders/dayvolume is well within EventStoreDB's documented capabilities.We explicitly chose not to build our own event store (Option B)because we've been burned before by building infrastructurein-house when proven solutions exist.## ConsequencesPositive: Full audit trail, state replay, clean separation ofwrite and read models.Negative: Team needs EventStoreDB training (estimated 1 week).Deployment complexity increases (new database to manage).Local development setup needs updating.We accept that eventual consistency between the event store andread models means order list views may lag by up to 500ms.
This ADR is worth more than a 50-page architecture document. Six months later, when a new developer asks "why are we using EventStoreDB?", the answer is right here: because of specific constraints, after considering specific alternatives, with explicit tradeoffs acknowledged.
Not every decision needs an ADR. I use this decision tree:
Is this decision easily reversible? If yes, don't write an ADR. Just make the decision.
Does this decision affect more than one team? If yes, write an ADR.
Will someone ask "why did we do it this way?" in 6 months? If yes, write an ADR.
Does this decision involve a significant tradeoff? If yes, write an ADR.
In practice, this means 2-5 ADRs per quarter for a team of 6-8 engineers. If you're writing more than that, you're being too granular. If you're writing fewer, you're missing important decisions.
In the codebase. Not in Confluence. Not in Notion. Not in Google Docs. In a docs/adr/ directory at the root of the repository. ADRs stored outside the codebase become invisible. ADRs in the repo show up in code search, appear in PRs when updated, and travel with the code when it's forked or migrated.
ADRs should go through PR review, just like code. The developer documentation guide explains how that review fits the wider documentation workflow. The author writes a draft, tags 2-3 reviewers, and the team discusses in PR comments. This is intentional. The PR discussion becomes part of the historical record. When someone reads the ADR later, they can click through to the PR and see the debate.[3]
# My Contrarian Take: ADRs Should Document Rejected Options in Detail
Most ADR templates give a brief nod to alternatives. I think the alternatives section should be the longest part of the document.
Here's why: the decision itself is usually obvious in hindsight. "Of course we chose PostgreSQL." But why didn't we choose DynamoDB? What would have made DynamoDB the right choice? Under what conditions should we reconsider?
Documenting rejected options does two things. First, it prevents re-litigation. When a new team member says "we should switch to DynamoDB," you don't have to rehash the entire discussion. Point them to the ADR. If the constraints have changed, great, write a new ADR. If they haven't, move on.
Second, it captures institutional knowledge about the problem space and helps address the knowledge concentration problem. The ADR becomes a mini research document about the decision domain. A well-written alternatives section teaches people about tradeoffs they might not have considered.[4]
If your team has zero ADRs today, here's the play: pick the last architectural decision that caused debate. Write the ADR retroactively. Put it in a PR. Let the team see the format. Then commit to writing one ADR for each significant decision going forward.
Don't try to document every past decision. That's a documentation project, and documentation projects die. Just start capturing decisions from today. In six months you'll have 15-20 ADRs, and that collection will be the most useful documentation your team has ever produced.
The bar isn't perfection. It's existence. A rough ADR that captures the "why" is infinitely more valuable than no ADR at all.
Frequently asked questions
What should an architecture decision record contain?
Capture the context, the decision, its status and its consequences. Include relevant alternatives and the rationale for the choice so a future reader can understand the trade-off without reconstructing the discussion.
When does a decision deserve an ADR?
Use an ADR for a choice with a significant effect on structure, dependencies, interfaces or other architectural concerns. The article's questions help the team decide when the historical rationale is worth preserving.
How should I change an accepted ADR?
Write a new record when the accepted decision changes. Preserve the original reasoning, mark its status as superseded and link to the replacement. Proposed records can be revised during the review process.
Should an ADR replace current architecture documentation?
It preserves the reason for a decision at a point in time. A reader may still need current diagrams, setup instructions and operational guidance. Use the decision record alongside the documents needed for the task.
Architecture fitness functions are automated tests for your system's structural properties. Here's how to implement the 5 most impactful ones and integrate them into your CI pipeline.
No single person can hold a large codebase in their head. A knowledge graph externalizes understanding into a queryable structure. Here's the 4-week playbook to build one.
Choose code search tools for text, symbols and cross-repository exploration. Use ripgrep, GitHub and Sourcegraph queries to find code and related changes.
Apply developer documentation best practices with ADRs, comments and tested examples. Use the WRITE system to keep changes reviewable and find stale guidance.