The short version
- An architecture decision record (ADR) is a short document that captures one technical decision: the context, the choice and its consequences.
- ADRs usually live in the code repository as numbered Markdown files, so the reasoning travels with the code.
- Tools range from plain Markdown to command-line generators to catalog sites. For most teams, plain Markdown is enough.
- The bigger gap is the many smaller decisions that never become an ADR.
An architecture decision record (ADR) is a short document that captures one significant technical decision: the situation that called for it, what was chosen, and what follows from the choice. ADR tools are the templates, generators and catalog sites that make those records quick to write and easy to find.
ADRs are one part of a wider habit: keeping a system of record for decisions. They cover the architecture. Other decisions need other homes, which this guide covers at the end.
What is an ADR?
The format comes from a 2011 blog post by Michael Nygard, and it has stayed popular because it is small. An ADR is usually one page with a handful of sections. Each record covers exactly one decision, gets a number, and is never rewritten. When a decision changes, a new ADR replaces it and the old one is marked as superseded.
The point is to answer the question every engineer asks about an unfamiliar system: why is it built this way? Without ADRs, that answer lives in the heads of whoever was there. With them, it lives next to the code.
A minimal ADR template
# ADR-012: Use the shared event queue between services
Status: Accepted (2026-09-30)
Deciders: Dana Kim (platform lead), payments and search leads
## Context
Direct calls between services caused chained outages in the last two incidents.
## Decision
New services publish events to the shared queue. Existing direct calls move over by Q2.
## Options considered
- Keep direct calls with retries. Rejected: hides the failure instead of containing it.
- Adopt a service mesh. Rejected: too much to run for a team this size.
## Consequences
Services can fail on their own. Debugging spans more hops, so tracing becomes required.When to write an ADR
Write one when a decision is hard to reverse, affects more than one team, or is likely to be questioned later. Good examples are choosing a database, splitting a service, adopting a framework, or changing how services talk to each other. Do not write one for a library upgrade or a naming choice. If the team argues about whether something deserves an ADR, it probably does.
The main ADR tools
ADR tooling comes in four weights. Start with the lightest one that works.
| Option | What it is | Best for |
|---|---|---|
| Markdown in the repo | A docs folder of numbered files and a template | Most teams. No setup, reviewed in the same pull request as the code |
| A command-line generator | A small tool that creates and numbers each new record | Teams where the habit keeps slipping |
| A static catalog site | Renders the Markdown records into a searchable site | Teams with enough records that finding one by hand is slow |
| A hosted docs tool | A wiki or docs platform with an ADR template | Teams that already live in that tool |
The open source adr-tools scripts and log4brains are common choices for the generator and catalog options. Whatever you pick, keep the records in plain text if you can. A record that sits next to the code gets reviewed with the code and moves with it. A record in a separate tool tends to drift away from the system it describes.
The decisions that never become an ADR
The hardest problem with ADRs is everything that falls below the bar. For every decision big enough for an ADR, a team makes dozens of smaller ones: a timeout value, a retry policy, a choice to skip a test in one service, a workaround for a vendor bug. Each is too small for a formal record. Together they explain most of why the system behaves as it does.
Those decisions usually live in pull request comments and chat threads, and they become hard to find once the person who made them is away or gone. Three habits help:
- Keep a light decision log next to your ADRs: one line per decision, linking to the pull request or thread.
- When a pull request makes a non-obvious choice, say why in the description, not only in a comment.
- In reviews, ask "should this be in the log?" when a choice will surprise the next reader.
ADRs for decisions outside engineering
The ADR format works for business decisions too. Pricing, hiring plans and go-to-market changes all benefit from the same context, decision and consequences structure. The team decision record adapts the format for those decisions. If several people need to weigh in before an architecture decision is made, run it through an RFC process first; the accepted RFC becomes the ADR.
Where StandIn fits
StandIn answers your teammates' questions from the work you have already done, in your words, with a source under every answer. When you are away, a teammate can ask why the services use the shared queue and get the answer from your ADR or your brief, with your name on it. When the reasoning was never written down, StandIn never guesses: it says so and points to the person who knows. See how StandIn works.
Parker Miller
Founder, StandIn
Parker Miller founded StandIn. He writes about coverage, handoffs, and what it takes for software to answer for a team from what people actually wrote down.
More about StandInOn your behalf. Never as you.
Every decision your team makes becomes something the next person can ask about, with the person who made it named as the source.
Keep reading
- A Decision Log Template for Engineering Teams (And Why It Goes Stale)A decision log template for engineering teams with every field explained, a filled-in example, the three fields most templates miss, and how to keep it current.
- What Is a Decision Log in Project Management?A decision log in project management records key project choices and why. What to capture, and why a queryable record beats a spreadsheet.
- How to Stop Losing Decisions in SlackDecisions made in Slack threads scroll away. Stop losing them by declaring each one into a record you can query later.
- From the productYour StandInYour work, ready to be asked. See what a StandIn knows, and what it never guesses.