ADRs: why architecture decisions should be written down
Six months on, nobody remembers why this database or this structure was chosen. An architecture decision record is a one-page note that keeps the reasoning behind each important decision and ends repeat debates.
In every software project there comes a moment when someone asks, "why did we build it this way?" and nobody has a precise answer. The person who decided has left, or forgotten, or the reason no longer holds and no one knows.
The architecture decision record is a simple answer to that.
What an ADR is
An ADR is a short document, usually one page, recording one important decision. Not the documentation of the whole system — one decision, its reasoning and its consequences.
A simple template
- Context: what situation made the decision necessary, and what constraints applied?
- Decision: what did we choose, in one or two sentences?
- Alternatives: what did we consider and reject, and why?
- Consequences: what does this make easier, and what harder?
The third section is the most important and the most often skipped. A decision without its rejected alternatives will be reopened in six months.
A real example
This is one of the recorded decisions behind this site, in summary:
Context: the site must run in development with no setup at all, yet have a dependable database in production.
Decision: a file-based database in development and PostgreSQL in production, both behind the same contract.
Alternatives: PostgreSQL everywhere (heavy local setup); a file-based database everywhere (too limiting in production).
Consequences: every schema change is written for both. In return, each developer gets a full environment with one command.
Those few lines answer a question that would otherwise come up again and again.
Which decisions deserve one
Not every decision needs an ADR. These do:
- Decisions that are expensive to reverse: the database, module structure, the authentication approach.
- Decisions that are surprising and will raise questions later.
- Decisions involving a deliberate trade-off.
- Decisions not to do something. Those need recording too.
Naming a variable does not.
Keeping them useful
- Keep them short. Nobody reads a ten-page ADR.
- Don't edit; supersede. If the decision changes, write a new ADR that replaces the old one. The history has value.
- Number them and keep them next to the code. Documents that live elsewhere go stale.
- Write them at the time. Two weeks later you will have forgotten half the reasons.
What the client gets out of it
- Less dependence on individuals. When someone leaves, their reasoning stays.
- Cheaper onboarding. A handful of ADRs replaces months of asking around.
- Defensible decisions. When an investor or technical auditor asks "why", there is a written answer.
Where ADRs sit in the process
In my process, architecture decision records are an output of stage three, alongside the system map, API contracts and the data model. It is also one of the standing principles: decisions are written down so they can be defended later.
ADRs complement the PRD: the PRD says what is built and why; the ADR says why it was built this way.
The takeaway
Writing an ADR takes ten minutes and saves hours of repeated debate. More importantly, it makes the product independent of anyone's memory.
Related: technical debt: when to accept it.