Architecture Decision Records: One Page, Not a Meeting

From the field: making the same decision twice

The outcome of that two-hour meeting was “keep the current setup”, so nothing changed. An outsider would say the meeting was wasted. I think something worse happened: we made the same decision for a different reason.

The reasoning eight months earlier — I found it later in an old chat thread — was operating cost, plus the fact that the team already knew that technology. The reasoning we produced was ordering guarantees. Both are reasonable, but they are different. Which means: when conditions change and ordering stops mattering, we will consider reversing the decision — even though ordering was never the real basis.

My share of the mistake: I did not write anything after that meeting either. I said “nothing changed anyway”. Three months later the same question came back.

One page, six headings

In teams where ADRs are complicated, they do not get written. Ours is this short:

# ADR-0023: Queue infrastructure choice

STATUS   : Accepted  (2026-04-18)
           [Proposed | Accepted | Superseded by ADR-00xx]
DECISION : We use queue X for order events.
AUTHOR   : one name
PRESENT  : people in the meeting (if it was not one person's call)

## Context
The situation at the time, the constraints, and what triggered it.
400k events per day; ordering matters per order; two people on
the team know this technology; budget X.
(The future reader does not know today. This part is for them.)

## Decision
What we are doing, one paragraph. Past tense, not imperative:
"We chose", "We will use".

## Consequences
What this makes easier and what it makes harder.
Writing the harder part is mandatory; otherwise the record
is an advertisement.

## Rejected options
- Y : why it was dropped (one sentence)
- Z : why it was dropped
- Doing nothing : why that was not enough

Four headings are required: context, decision, consequences, rejected options. The rest is optional. It takes 20 minutes, and those minutes should be spent right after the meeting that made the decision — by the next day, half the reasoning has evaporated.

Why rejected options is the most valuable part

A year later, nobody asks “why did we do this”. What we did is visible; the code is right there. The question is always this: “Why didn’t we do that?”

Without that section, the only way to answer is to redo the research. With it, the answer takes thirty seconds — and more importantly, the answer is not “we tried it and dropped it”, it is “we dropped it for this reason back then, is that reason still true?” It does not stop anyone reopening the decision. It makes sure they reopen it from the right place.

We also made a habit of putting “doing nothing” on the list. It is the most serious competitor to most architectural decisions, and it is usually never discussed.

Which decisions get recorded

Without a clear line, teams fall to one extreme or the other: nothing gets written, or an ADR is demanded for every PR and by month three nobody writes one. Our test is a single sentence: would undoing this decision in six months take longer than a sprint? If yes, record it.

The status field: records are never deleted

The most common mistake is updating the old record when the decision changes. That erases the history and turns the file into an ordinary document describing “the current state” — which is what the code is for.

ADR-0023  STATUS: Superseded by ADR-0031   (2027-02-10)
          (the content stays EXACTLY as it was, one line is added)

ADR-0031  STATUS: Accepted (2027-02-10)
          ## Context
          In ADR-0023 we chose X. The reasoning then was 400k
          events per day. Today it is 3 million and ordering
          per partition is enough. The conditions changed,
          so the decision changed.

The chain gives you one more benefit: a new joiner can read the sequence of decisions. The answer to “why is it like this” is usually not in one decision, but in three of them stacked on top of each other.

Where they live, who writes them

Records live in the repo, under docs/adr/, in the same pull request as the code. The reason is the same one that made us move runbooks out of the wiki: a document that does not change with the code is not updated, and within six months it starts actively giving wrong information.

The author is defined too: the person who walks out of the meeting where the decision was made. An ADR delegated to someone else does not get written. The record is reviewed as part of that PR — and the section that draws the most comments is usually “consequences”, because people skip writing down what the decision makes harder.

What to track

What did not work for me

• Writing ADRs retroactively. We said “let us document the last two years of decisions”. Six records were written, all full of generic sentences, because nobody remembered the constraints of the time. A record is only valuable at the moment of the decision; written later, it is guesswork.
• Adding sections to the template. We added “risks”, “cost analysis” and “alternative architecture diagram”. Writing time went from 20 minutes to two hours, and the number of records went to zero. We reverted it.
• Adding an approval process. Making ADRs “approved by an architecture board” turned writing a record into bureaucracy that got in front of making a decision. Now the record is not the decision, it is the write-up of the decision; if approval is needed, it already happened in the meeting.

Checklist

Conclusion

That two-hour meeting cost four people half a day and changed nothing. Twenty minutes from one person eight months earlier would have made it unnecessary — or better: we would still have had the meeting, but it would have started from “have the conditions changed?” instead of from scratch.

A decision record is not a documentation habit. It is a discussion-shortening tool. It pays you back not when you write it, but a year later when someone opens it.

The test is simple: can the newest person on the team find the reasoning behind your most contested architectural decision on their own? If not, that reasoning lives in one person’s head, and one day that person leaves.