Demystifying ADRs
A few months into a project, someone new always asks the same kind of question: “Why did we set it up this way?” And suddenly three people are telling three different stories about a choice nobody wrote down.
That is the problem ADRs solve — and no, you do not need to be an architect to use them.
ADR stands for Architectural Decision Record. The name sounds formal, but the idea is simple: a short note that explains an important decision while you still remember why you made it.
Think of it like a journal entry for a fork in the road — not a manual for the whole project.
What is an ADR, in plain English?
An ADR answers five questions on one page (or less):
- What was the situation? — What problem were you trying to solve? What limits did you have (time, budget, tools you already use)?
- What did you decide? — The choice, in a clear sentence.
- What happens because of that? — What gets easier? What gets harder? What are you giving up?
- What else did you consider? — The options you said no to, and why.
- What has to happen to make it real? — Not step-by-step instructions — just the big pieces that need to exist before the decision actually lands.
That is it. You are not writing a novel. You are leaving a breadcrumb for your future self — and for anyone who joins later.
Why bother?
People forget. Documents do not. The person who made the call might change teams. The Slack thread gets buried. The ADR stays.
You stop having the same argument twice. When things change, you read the old note, mark it as outdated, and write a new one with the updated reasoning. You are not starting from zero.
New people ramp up faster. They learn not just what you built, but why it looks the way it does. A lot of “this seems complicated” moments make sense once you read the note behind them.
Writing clarifies your thinking. I have changed my mind halfway through writing an ADR more than once. That is a feature, not a failure — better to catch a weak idea on paper than in production.
When to write one
Write an ADR at the moment of the decision, not at the end of the project when memories are fuzzy.
Good candidates:
- Picking a database or a major tool
- Choosing how two systems talk to each other
- Security or privacy boundaries (“who can see what”)
- Anything that would be painful to undo later
Skip it for small stuff — typo fixes, routine updates, preferences that are easy to change tomorrow.
How I use them
One decision per note. “Our whole platform plan” is too big. “We will use X for job scheduling because Y” is the right size.
Number them. Decision #1, Decision #2, and so on. Easy to refer to: “That changed in Decision #7.”
Keep them where the work lives. I put mine in a docs/adr/ folder next to the code, as simple markdown files. They get dated, searchable, and they stay in history when things change — you do not delete the old note when you change your mind; you mark it replaced and write a new one.
Share them with the team. Treat big decisions like anything else worth a second pair of eyes before you lock them in.
Add a diagram when words are not enough
I have found that a simple diagram or flowchart helps a lot — sometimes more than another paragraph.
Architecture decisions are rarely about one box in isolation. They are about how things connect: who sends what to whom, what happens when something fails, where data lives before and after the change. Text alone can describe that, but a picture lets someone grasp the whole flow in seconds.
You do not need fancy tools. A quick sketch in Excalidraw, Mermaid in markdown, or even a photo of a whiteboard is enough. The goal is not a polished slide deck — it is shared understanding.
What I usually diagram:
- Before and after — what the system looked like vs. what we are moving toward
- Happy path flow — the normal route a request or message takes
- Failure path — where errors go, what retries, what stops the line
- Ownership boundaries — which team or service owns which piece
If the diagram and the written decision disagree, that is useful too — it usually means the decision is not as clear as you thought.
An ADR is not a vote. It records what was decided (or what is being proposed). The team still has to actually agree before you treat it as final.
An ADR is not a build guide. The implementation section names what has to happen — provisioning, migration, training, sign-off — not how to click every button. Save the how for runbooks and tickets.
Habits that helped me
| Habit | Why |
|---|---|
| Keep it short | One screen. If nobody reads it, it did not help. |
| Add a simple diagram | Shows how pieces connect and flow — faster than reading three paragraphs. |
| List what you rejected | ”We almost went with Z” saves the next person from reopening a settled debate. |
| Date it | Context changes. A note from 2024 explains choices that look odd in 2026. |
| Say who decided | Not for blame — for clarity when someone has a follow-up question. |
| Mark the status | Draft, accepted, outdated, replaced by Decision #9 — so nobody treats an old note as current law. |
A template you can copy
Save this as something like docs/adr/0001-short-title.md and fill in the blanks:
# 0001. Short title describing the decision
- **Status:** draft | accepted | outdated | replaced by [0009]
- **Date:** YYYY-MM-DD
- **Decided by:** names or roles
## The situation
What problem are we solving? What constraints do we have?
## The decision
We will …
## What that means
### Upsides
- …
### Downsides / trade-offs
- …
## Other options we considered
| Option | Why we passed |
|--------|----------------|
| … | … |
## Implementation — what has to happen
High-level checklist only. What needs to exist or get done before this decision is truly in place?
- **Prerequisites:** tools, access, budget, approvals, or other decisions that must come first
- **Work required:** major steps in rough order (e.g. provision service → migrate data → cut over traffic)
- **People / owners:** who needs to be involved or sign off
- **Rollout shape:** big-bang vs phased, pilot group, rollback trigger if something goes wrong
- **Done when:** how you know implementation is complete — not perfect, just real
## Diagram (optional but worth it)
Embed or link a simple flowchart, sequence sketch, or before/after picture.
What to show: how components connect, the main flow, and where failures go.
Tools: Excalidraw, Mermaid, whiteboard photo — whatever is fastest.
The other options section is the most valuable part. That is where you stop the next “why didn’t we just…?” conversation before it starts.
The implementation section bridges “we decided” and “someone still has to go do six things.” Without it, ADRs can feel like philosophy that never touches the ground.
A diagram is the fastest way I have found to get everyone looking at the same picture — especially when the decision changes how things wire together.
What changed for me
Once this became a habit, meetings got shorter because the thinking happened on the page first. When something went wrong, I could tell the difference between a mistake and a documented trade-off we knowingly made. And I spent less energy re-explaining the same choices every quarter.
If you are building anything meant to last, your first ADR can be delightfully meta: Decision #1: We will write down important decisions. It sounds silly. It works.
The next time someone asks “why did we build it this way?”, you will have an answer — not “ask whoever was here back in the spring.”