ADR stands for architecture decision record. An ADR is a short document, usually one page, that captures a single important technical decision: what was chosen, why, and what the team gave up to choose it. It exists so that someone who reads it later understands the reasoning behind a system without having to find and ask the people who built it.
If you have ever inherited code and wondered "why on earth is it done this way?", you have felt the problem an ADR solves. The code answers what. The ADR answers why.
What does ADR mean?
ADR means architecture decision record. Break the three words down and the meaning is plain. "Architecture" signals that the decision shapes the structure of a system, not a small detail. "Decision" is the choice itself. "Record" means it is written down and kept, so the reasoning survives after the conversation ends.
The "architecture" part is worth a second. It does not mean only grand, system-wide choices. It means decisions that are significant and costly to reverse: which database to use, how services communicate, whether to adopt a framework, how authentication works. These are the calls that shape years of work, and they are exactly the ones whose reasoning tends to vanish.
What does an ADR look like?
An ADR is short and follows a simple shape. A common version has just a few parts:
- Title: a short name, often numbered, like "ADR-007: Use Postgres for the events store."
- Status: proposed, accepted, deprecated, or superseded.
- Context: the situation and constraints that forced a decision.
- Decision: the choice, stated plainly.
- Consequences: what follows, the good and the bad, including the tradeoffs you accepted.
That is the whole thing. One page, plain language, one decision. The discipline is in keeping it focused. An ADR that tries to cover five decisions stops being useful, because nobody can find the one they need.
How do you write your first ADR?
You can start in about ten minutes. Here is a quick path.
First, pick a real decision you just made or are about to make, ideally one that was hard to reverse or that people disagreed about. Those make the clearest ADRs. Second, write the context in a few sentences: what problem you were solving and what constrained you. Third, state the decision in one line. Fourth, list the consequences, and be honest about the downsides, because a decision with no recorded cost reads as if it were free. Fifth, set the status to "accepted" and give it a number.
Number them in order, so ADR-001, ADR-002, and so on. When a later decision overturns an earlier one, do not delete the old ADR. Mark it "superseded by ADR-014" and keep it. The history of how thinking changed is part of what makes the record valuable.
How is an ADR different from a decision log?
People mix these up, so a quick table helps.
| Trait | ADR | Decision log |
|---|---|---|
| Scope | One technical decision per record | Many decisions over time |
| Depth | Detailed: context, choice, consequences | Often brief entries |
| Focus | Architecture and structure | Any team decision |
| Format | One page per decision | A running list or queryable record |
An ADR is one record for one decision. A decision log is the broader collection of decisions a team makes, which may include ADRs alongside product calls, process changes, and other choices. Think of the ADR as a single well-documented entry and the decision log as the place all such entries live.
Why does it matter how ADRs are stored?
Writing the ADR is half the job. Being able to find it later is the other half, and it is where most teams quietly lose the value. ADRs are usually stored as static files in a repo folder. That works until the folder grows, and then finding the one decision you need means scrolling and guessing at filenames.
The better setup lets you ask the record a question and get the right decision back, with the name of the person who stood behind it. That is the model StandIn is built on. Decisions become discoverable and pointable, and each person gets a Representative, called your StandIn, that answers only from records they explicitly stood behind. It will not invent a rationale. When no ADR exists for your question, it says so and points you to the right person, which is more honest than a confident guess and saves you from acting on a decision that was never made.
For the fuller explainer on what an architecture decision record contains and when to write one, see our complete guide to ADRs. If you want to set up the broader collection, our decision log template for engineering teams gives you a starting structure.
Frequently Asked Questions
What does ADR stand for?
ADR stands for architecture decision record. It is a short document that captures one significant technical decision, the reasoning behind it, and the consequences the team accepted.
How long should an ADR be?
An ADR should be short, usually about one page. It covers a single decision with enough context to make the reasoning clear, and no more. Long ADRs tend to lose the reader and bury the point.
Is an ADR the same as a decision log?
No. An ADR is one record for one technical decision. A decision log is the broader collection of decisions a team makes over time, which can include ADRs alongside other choices.
When should you write an ADR?
Write one when a decision is significant and hard to reverse, such as choosing a database or changing how services communicate, especially when people disagreed about it. Skip routine, easily reversed choices.
What should you do with an outdated ADR?
Do not delete it. Mark its status as deprecated or superseded by the newer ADR and keep it. The record of how a team's thinking changed is part of the value.
Get async handoff insights in your inbox
One email per week. No spam. Unsubscribe anytime.
Ready to retire your daily standup?
Distributed teams use StandIn to start every shift with full context, no standup required. Engineers publish a 60-second brief. The next shift wakes up knowing exactly what to work on.