ADRs and Decision Logs: Why They Go Stale, and What to Do About It
What an ADR is, a template you can copy, and an honest look at why your team's decision log stopped getting updated after the first sprint.
Every codebase is full of decisions that made perfect sense at the time. Then the person who made them moves teams, and the next engineer finds a strange lock around the billing job, assumes it's leftover junk and deletes it. ADRs exist to stop that from happening. They mostly don't, for reasons we'll get to, but the idea is sound.
What is an architecture decision record?
An architecture decision record, or ADR, is a short note about one technical decision and why your team made it. It's not a design doc or a spec. It's closer to a receipt: here's what we chose, and here's what it cost us.
The format was popularised by Michael Nygard in a 2011 post called Documenting Architecture Decisions, and most templates you'll find today are variations on his. They're usually kept as numbered markdown files in the repo, in a folder like docs/adr, so they live next to the code they explain.
A decision log is the collection of those records, or sometimes a simpler list of decisions with a line or two each. Same idea, less ceremony. Code tells you what the system does and git blame tells you who to ask. The decision log is meant to tell you why, so you don't have to ask anyone at all.
A copyable ADR template
This is Nygard's format with a few additions that pay off later, mainly the alternatives and links back to where the decision actually happened. Save it as docs/adr/0001-short-title.md and fill it in. If a section would be empty, delete it rather than writing N/A with great solemnity.
# 0001. Short title of the decision
Date: YYYY-MM-DD
Status: Proposed | Accepted | Superseded by 00XX
Deciders: who made the call
## Context
What problem are we solving, and why does it need a decision now?
Constraints, deadlines, incidents, anything that rules options out.
## Decision
What we're going to do, in one or two plain sentences.
## Alternatives considered
- Option A: why we didn't pick it
- Option B: why we didn't pick it
## Consequences
What gets easier, what gets harder, and what trade-off we're accepting.
## Revisit if
The signal that would tell us this decision is now wrong.
## Links
The PR, issue, Slack thread, postmortem or benchmark behind it.A short example
Here's what a filled-in one looks like. Note how little there is.
# 0014. Use a Postgres advisory lock for the nightly billing job
Date: 2026-03-04
Status: Accepted
Deciders: Billing team
## Context
A deploy overlapped with the cron window and the nightly billing job
ran on both app servers at once. Some customers were charged twice.
We need exactly one copy of the job running at a time.
## Decision
The job takes a Postgres advisory lock before it starts, and exits
quietly if another process already holds it.
## Alternatives considered
- Redis lock: we'd be adding Redis to the stack for one job.
- Only run cron on one server: breaks the day that server is replaced.
## Consequences
No new infrastructure. The lock lives with the database connection,
so a hung job keeps it until the connection dies. That's fine for
something that runs once a day.
## Revisit if
Billing moves off Postgres, or the job needs to run in parallel.
## Links
Postmortem: double billing on 2 March. PR #482.Nobody is going to frame it. But in a year, when someone looks at that lock and thinks they can simplify it, this is the file that stops them from double billing your customers again.
ADR, decision log or design doc?
| Format | What it is | Use it when |
|---|---|---|
| ADR | One decision, its context and its trade-offs | Someone is going to ask why later, and you won't be around to answer |
| Decision log | The index of decisions, often a folder of ADRs or a running list | You want one place to check what's already been decided |
| Design doc | A proposal for how to build something, written before the work | The change is big enough to need discussion first. It often produces a few ADRs |
Why most teams stop writing them after a sprint or two
Here's the honest part. Plenty of teams adopt ADRs with real enthusiasm, write a flurry of them in the first couple of weeks and feel very organised. Then the flurry stops. Ask around and you'll hear some version of the same story: the decision log was great for the first sprint and nobody has touched it since.
Where it goes wrong
- 1
Writing it is a separate job
The decision happens in a PR comment or a Slack thread. The ADR is homework you're meant to do afterwards, and homework loses to shipping pretty much every time.
- 2
The moment passes
By the time anyone remembers to write it up, the context is fuzzy and the person who made the call is on leave. So it gets put off again, and then it's too late to bother.
- 3
Nobody reads them
If the ADR folder never comes up during review or design, it's write-only storage. People stop writing things nobody reads, which is honestly quite rational of them.
- 4
The process grows
Someone adds an approval step, then a template with eleven sections. Now writing the ADR takes longer than making the decision, so people just make the decision.
- 5
Old records never get updated
The code moves on but the ADR still says Accepted. After one bad experience with an out-of-date record, people stop trusting the whole folder. Stale context is worse than none, because it looks authoritative.
None of this is really about discipline. The log sits next to the work instead of inside it, so it relies on someone remembering to go and update it. Anything that relies on someone remembering is on borrowed time.
How to keep a decision log alive
Habits that actually stick
- 1
Record it at the moment of decision
Write it when the thread converges or the PR gets approved, not at the end of the sprint. A rough record written now beats a polished one that never happens.
- 2
Keep it short
Aim for something you can write in ten minutes. The template above is a ceiling, not a target. A context and a decision on their own are still far better than nothing.
- 3
Ship it with the PR
Add the ADR in the same PR as the change it explains, or link it from the PR description. Reviewers see it while they're looking at the code, which is the one moment someone is guaranteed to be paying attention.
- 4
Link every decision back to its source
Point to the PR thread or postmortem that drove it. When someone doubts the record later, they can check the original conversation instead of taking the ADR's word for it.
- 5
Supersede, don't delete
When a decision changes, write a new record and mark the old one as superseded by it. Why you changed your mind is often more useful than what you originally decided.
- 6
Bring them up in review
If a change goes against an accepted ADR, say so in the review. Either the code is wrong or the ADR is out of date, and you want to know which.
Your team never writes docs, and Prodigent still knows why
Prodigent picks up decisions from your PRs and Slack threads as they happen, then shows them to whoever is reviewing a change that goes against one. A person still makes the call. Keep writing ADRs if you like, it just matters a lot less when someone forgets.
Try Prodigent free