Some technical debates never die. They just wait for a new teammate.
Three months after the team chooses PostgreSQL over MongoDB, someone asks why. Six months after moving jobs to a queue, someone suggests doing them inline again. A year later, nobody remembers the tradeoff, only the result.
That is where an architecture decision record earns its keep.
What an ADR is
An architecture decision record, or ADR, is a short note explaining one technical decision.
Not a huge design document. Not a meeting transcript. Just the decision, the context, the options, and the consequence the team accepted.
The point is memory. Future developers should know why a choice made sense at the time, even if they would choose differently today.
When you should write one
Do not write an ADR for every small choice. That turns documentation into paperwork.
Write one when the decision is hard to reverse, affects multiple parts of the system, or keeps coming back in discussion.
Good ADR topics include:
- choosing a database
- adopting a queue
- moving from REST to GraphQL
- picking a deployment model
- changing authentication flow
- deciding how services talk to each other
If the decision can be undone in one afternoon, a code comment may be enough.
The tiny ADR format that works
Small teams need a format people will actually use.
Try this:
# Use PostgreSQL for billing data
Date: 2026-06-28
Status: accepted
## Context
We need reliable relational constraints for invoices, payments, refunds, and account credits.
## Options
1. PostgreSQL
2. MongoDB
3. External billing-only store
## Decision
Use PostgreSQL as the source of truth for billing data.
## Consequences
Reporting is simpler and constraints are easier to enforce. Some document-shaped data will need explicit tables instead of flexible JSON blobs.That is enough. The value comes from writing it while the tradeoff is still fresh.
ADRs stop circular arguments
The best use of an ADR is not “look how disciplined our team is.”
It is this sentence: “We already decided that, here is why.”
That does not mean the old decision can never change. It means the new debate starts with the old context. If the context changed, write a new ADR that replaces the old one.
Without that memory, teams replay the same argument with less information each time.
Keep status boring
Use a tiny status list:
| Status | Meaning |
|---|---|
| proposed | We are considering this. |
| accepted | This is the current decision. |
| superseded | A newer ADR replaced it. |
Avoid clever labels. Documentation should not need its own manual.
Where to store ADRs
Put them in the repository, usually under docs/adr/.
That keeps decisions close to the code they affect. It also makes ADRs part of code review, so the team can challenge the reasoning before it becomes “history.”
A wiki can work, but only if the team reads it. Most teams forget wikis exist until someone needs onboarding material.
What not to put in an ADR
Do not dump every Slack argument into the file.
Skip vague claims like “this is more scalable.” Say what scale you mean. Requests per second, team size, data volume, deploy frequency. Pick the real constraint.
And do not pretend the decision has no downside. If the ADR hides the tradeoff, future readers will distrust it.
A useful ADR has a point of view
The strongest ADRs sound a little opinionated because real decisions are opinionated.
“We picked this because it fits our current team and product” is better than a fake neutral comparison table that refuses to choose.
Software architecture is full of expensive maybes. ADRs make the maybe visible.
That alone can save a small team from having the same meeting forever.
