Why I ask for an ADR before every architecture decision
Writing an ADR means slowing down at the right moment, before you decide.
An ADR, an Architecture Decision Record, is one page. Context, decision, consequences. Three paragraphs, no more.
The idea comes from Michael Nygard, in 2011. It hasn’t aged a day.
What it changes in a team
- You stop rehashing the same decision every six months.
- A new hire reads ten ADRs and understands why the code looks the way it does.
- An AI reading the repo finds the rules of the game: it’s a free, feedforward guide.
That’s why I ask for them in every team I join.
The classic trap
Writing the ADR after the fact, to justify a decision already made.
An ADR is written before, while you’re still hesitating. If there’s no serious alternative, there’s no need for an ADR.
Where to keep them
In the repository, a docs/adr folder, one file per decision, numbered. No tool, no wiki. Markdown is enough, and it lives with the code.
Unlike a rule a CI pipeline can check, an ADR stays an intention. But a written, dated intention that anyone can find again.
It’s also the history the code alone can’t tell: why this decision, and not another.
Happy designing!