Decisions you can still understand in two years

Every system older than a year has places where a new team member asks: “why is this like this?” And the honest answer is too often: “the only person who knows has left.” The remedy costs almost nothing: document architecture decisions at the moment they are made, with the context that forced them. Not as prose for posterity, but as a short, dated note with three things in it: what was decided, which alternatives were on the table, what tipped it.

An ADR is a page, not a document

An Architecture Decision Record records what was decided, why, and what you accept in exchange. It has four sections and fits on one screen:

• Context – what was the situation? What constraints were there?
• Decision – what are we doing?
• Alternatives – what did we reject, and why?
• Consequences – what becomes easier, what becomes harder?

It lives in the repository, next to the code it explains. Not in the wiki, not in a ticket, not in a Slack message.

Why this beats any documentation

In practice the distinction is simple. Documentation describes how a system is. It goes out of date the moment the system changes. An ADR describes why it became that way. That never goes out of date — even when the decision is later reversed, the record stays true. You add a new one that references the old.

A system without a decision history is like a contract without a date. You can read it, but you cannot place it.

How we handle it day to day

• Every decision that is hard to reverse gets an ADR. Database choice, module boundaries, auth model: yes. Button colour: no.
• The ADR is written before implementation and reviewed in the same pull request.
• Numbered, chronological, never deleted. A record is superseded by a new one, not by editing.

The cost: twenty minutes per decision. The return: a team that after the third round of staff changes still knows why the system looks the way it does.