ADRs are the most underrated documentation practice. Here's how to write them well and integrate them into your development process.
Why ADRs matter more than they look
Most teams do not lose months because of bad code. They lose months because the next engineer cannot tell why the code is the way it is, so they rebuild it, rip it out, or layer around it. The original decision lives in a Slack thread that nobody can find anymore.
Architecture Decision Records are the cheapest fix for this I know. A short, dated, written record of a meaningful decision and why it was made. Boring on the surface, transformative in practice. I have introduced ADRs on every team I have worked with that did not already have them, and I have never had a team thank me for any single piece of process more.
What an ADR actually contains
The format is forgiving. The discipline is in writing one at all. The structure I use, lifted with minor adjustments from the original Michael Nygard template:
- Title. Short, declarative
- Status. Proposed, accepted, deprecated, superseded
- Context. What is the situation? What forces are at play? What constraints?
- Decision. What we are doing
- Consequences. What follows from this, both good and bad
- Alternatives considered. What we looked at and why we did not pick them
That is it. No diagrams unless they help. No five pages of background. The whole thing should fit on one screen in most cases.
The point is the consequences section
The decision is the obvious part. The consequences section is where ADRs earn their keep.
When I write consequences honestly, I am forced to admit the costs of the decision, not just the benefits. "We get faster onboarding, but we lock ourselves into this vendor for at least 18 months." "We avoid the database migration now, but we will pay for it when we add the second tenant." The act of writing those down changes the conversation. Sometimes it changes the decision.
A future engineer reading the ADR can also see, at a glance, whether the costs the team accepted have started to bite. That tells them whether the decision still holds or whether it is time to revisit.
Where ADRs live
I keep ADRs in the same repository as the code they describe, in a top-level docs/adr/ folder, numbered sequentially. Each ADR is a single Markdown file. They are committed and reviewed in pull requests just like the code they accompany.
Why in-repo? Because the code and the ADR drift apart immediately if the ADR lives somewhere else. If you can change the code without anyone touching the ADR, the ADR is already wrong.
When to write one
I write an ADR for any decision that meets one of these tests:
- It will outlast the people in the room
- It commits the company to a vendor or platform
- It changes a contract that other teams or services depend on
- It introduces a new pattern that will be replicated
- It deliberately diverges from a default that was working
I do not write an ADR for a Friday refactor or a tweak inside a single file. The cost of process should match the cost of the change.
In my experience, teams that try to ADR-everything burn out within a quarter. The ADRs become a chore, the chore becomes resented, the practice dies. Better to write one a month that everyone reads than fifty a month that nobody does.
Writing the first one is the hardest
The first ADR on a project always feels strange. The team has been making decisions for months without one, so writing one now feels like overkill. Push past that. Pick the most consequential live decision, write the ADR for it, and circulate it as an example.
The second ADR is much easier. By the fifth, the team has a rhythm. By the tenth, someone who joined two months earlier will read them all in an afternoon and understand the system better than half the people who built it.
Make ADRs part of code review
The ADR should land in a pull request, with the affected code, ideally before the code is merged. Reviewers should be able to push back on the decision, not just the syntax. This is where the practice goes from documentation to design tool.
A few small habits that keep this healthy:
- Reviewers comment on the ADR file the same way they comment on code
- The author updates the ADR as feedback lands, not in a separate doc
- Once accepted, the ADR is rarely edited; instead a new one supersedes it
- A short link to the relevant ADR appears in the code that implements it
Superseding instead of editing
ADRs are immutable in spirit, mutable only by being replaced. When the world changes, you do not edit the old ADR. You write a new one with status accepted, set the previous one to superseded, and link them.
This matters because the old ADR is still the right explanation for why the code looked the way it did when someone wrote it. Editing the past hides the path.
What ADRs are not
ADRs are not a substitute for system documentation. They tell you why a decision was made, not how the system works today. Both are valuable. They serve different needs.
ADRs are also not a place for political compromise. If the team is split on a decision, write the ADR for the one you actually picked, and use the alternatives section to explain what you did not do. A wishy-washy ADR is worse than no ADR.
The takeaway
ADRs are one of the highest-leverage practices a team can adopt and one of the easiest to ignore. A short, honest record of why we are doing this, kept in the repo, written when the decision is fresh, reviewed alongside the code. Boring, cheap, transformative.
If you want help introducing ADRs and a broader engineering practice on a team, that is exactly the kind of advisory work I do, often as part of a start project engagement.
References
Tagged
Sri Vardhan
Independent technology studio of one. I help founders and small teams ship serious software without the consultancy overhead. More about me.