Listed Buildings, Listed Decisions: A Register for Your Codebase

Walk down almost any respectable London street and you will find a blue plaque: a small, polite disc saying that somebody important once slept, argued, or invented something behind that brickwork. It is not a history of the building. It is a claim about why the building matters.

Good software teams need something similar, but for decisions. Not a commit log. Not a wiki page nobody reads. A small, durable note attached to the place where a choice lives, saying: this bit is load-bearing, and here is why we built it this way.

Architecture decision records are that plaque. They are cheap to write, easy to ignore, and enormously useful when the heating is off, the build is red, and someone is asking why the payments service talks to a queue instead of a database.

A plaque is an argument, not a diary

The mistake is treating decision records as minutes. You do not need a transcript of every meeting, a roll-call of who said what, or a blow-by-blow account of the three weeks you spent arguing about naming. A plaque does not say that a committee met on Tuesday. It says that this matters.

So an ADR should make an argument for the current shape of the system. It should capture the forces at play, the choice made, and the consequences accepted. It should be honest about what got worse as well as what got better. That last part is what turns a note into a useful tool rather than a press release.

For a UK team, think listed building consent rather than a blog post. If you want to knock through a wall in a Grade II listed property, you need to know what the conservation officer cared about and why. If you want to change a queue topology, you need to know what the previous team was protecting.

What earns a plaque

Not every decision deserves one. Plaque inflation is real. If you record every variable rename and every library bump, the important records disappear into a fog of low-stakes paperwork.

Aim for decisions that are expensive to reverse, surprising to a newcomer, or likely to be re-litigated. Choosing Postgres over MySQL? Maybe. Splitting a monolith into services? Definitely. Deciding to store money in integer pence rather than floating point? Absolutely. Deciding to use one HTTP client over another? Probably not, unless there is a compliance or support reason that will outlive the current sprint.

A useful test: would a sensible engineer, six months from now, be tempted to change this without knowing the original constraints? If yes, write it down. If no, let it go. The plaque is for the load-bearing choices, not the paint colour.

The inscription is deliberately short

A good ADR fits on a page. It has a title, a status, a date, and three short sections: context, decision, consequences. Some teams add alternatives considered, which is useful when the rejected option is the one everybody will suggest again next quarter.

Keep the language plain. We chose X because Y. We accepted Z. If A changes, revisit this. That is enough. You are not writing a design document for an auditor; you are leaving a note for a colleague who is tired, under pressure, and standing in front of a failing test.

The status field matters more than people expect. Proposed, accepted, superseded, deprecated. A decision that is no longer current should not be deleted. It should be retired with a link to its replacement. That way the history of the argument stays visible, even if the conclusion has moved on.

Where the plaques live

Put them in the repository. Not in a shared drive, not in a wiki that requires three clicks and a login, not in a Confluence space owned by a team that was reorganised last spring. The repository is where the code lives, where reviews happen, and where the next person will look first. A docs/decisions folder with numbered Markdown files is enough. No special tooling required.

If you already have a README, link to the decision log from it. If you have a pull request template, add a line asking whether this change needs a record. Keep the friction low. The moment writing an ADR feels like a formal governance process, people will route around it.

Writing for the person at 2am

The audience is not the architecture review board. It is the engineer who gets paged at 2am and discovers that the retry logic is deliberately weird. They need to know whether the weirdness is a bug or a decision. They need to know what happens if they fix it.

So write down the sharp edges. We retry three times because the supplier API returns a transient 502 under load. We do not retry the final step because it is not idempotent. If you change this, speak to the payments team first. That is worth more than a diagram.

Also write down what you rejected. It saves the next person from re-running the same experiment. It also makes the record fair: you are not pretending the chosen path was obvious.

Retiring a plaque without bulldozing the building

Decisions age. The supplier changes its API. The team grows. The regulation shifts. A good decision record is not a promise to keep the same architecture forever; it is a marker of what was true when the choice was made.

When a decision no longer holds, supersede it. Add a new record, link the old one, and explain what changed. Do not quietly edit the old record to match the new world. That is how folklore starts. The value is in the trail, not in a tidy fiction.

Start with the next decision

You do not need a grand rollout. Pick the next significant change on your roadmap. Before the pull request merges, write one page: context, decision, consequences. Put it in the repo. Link it from the PR. See whether it helps in the next review.

If it does, do it again. In a year, you will have a small register of the choices that keep your codebase standing. Not a museum. Not a bureaucracy. Just a set of plaques for the people who come after you, saying: this mattered, and here is why.