Every system is a pile of decisions, and the code only records the outcome. Six months later someone asks why the database is shaped this way, and the person who knew has moved on. An Architecture Decision Record, or ADR, is a one-page note written when the decision is made, and it's the cheapest fix for that problem I know.
We write one for every decision that would be expensive to reverse, as a markdown file in the repository next to the code it explains.
The code tells you what, never why
A schema, a queue, a retry policy: you can read all of them. What you can't read is the constraint that made them that way, or the option the team tried first and dropped. Without that, every change starts with a guess. Is this structure deliberate, or just what the first engineer knew? Can we remove it, or does something far away depend on it?
Engineers answer that in one of two ways. They guess, which is how outages start, or they reverse-engineer the context from git blame and old chat threads, which is how a one-day change becomes a week.
An ADR is four short sections
Context: the problem and the constraints at the time. Decision: what we chose, stated so it can be checked. Alternatives: what else was on the table and why it lost. Consequences: what gets easier, what gets harder, and what decision this forces next.
The alternatives section is the one that pays. It stops the next engineer from spending a week rediscovering why the obvious option was rejected.
Here's the shape of a real one of ours, with the product details removed:
Decision: The database is the single source of truth for platform state. No state lives only in the orchestrator.
Alternatives: Keep state in custom orchestrator resources. That's native to the tooling, but it means two systems to reconcile and two to back up.
Consequences: One place to query, back up and audit. In exchange, an operations table adds about 30% more database writes, and the team gives up the orchestrator's own tools for inspecting internal state.
Three lines, and they shaped hundreds of later decisions. It took about fifteen minutes to write.
Why teams skip them, and why the reasons don't hold
"We don't have time." The decision took hours or days of discussion; the record takes fifteen minutes. "Everyone already knows." Today they do, but the engineer you hire next quarter doesn't. "It feels like bureaucracy." An ADR needs no approval and no review board. It records a decision that's already made.
The honest cost is discipline, not time. The ADR has to be written in the same change as the decision, or it doesn't get written. We've had ADRs land a week late, and those are the ones with the thinnest alternatives sections, because by then nobody remembers what else was considered.
How we keep them useful
They live in the repository, in docs/adr/, numbered in order, like 0047-database-source-of-truth.md. They're versioned with the code, searchable, and they move with the codebase when it changes hands. They're not in a wiki that drifts.
We never delete one. When a decision changes, the old ADR is marked superseded and links to the new one, so the reasoning behind the change survives too.
To start, don't backfill. Write an ADR for the next decision your team argues about, and put it in the pull request that implements it.
What to ask an engineering partner
If you're hiring a team to build your product, ask to see the ADRs from a past project. A team that has them can explain its own system to you, and to whoever maintains it after them.
A team that doesn't may still be good, but its knowledge leaves when it does. Every platform we hand over comes with its decision record.
ADRs are part of the Blueprint phase in The Perizer Protocol, which includes our ADR template.