A short guide to architecture decision records

We end up explaining this on discovery calls often enough that it deserved writing down. Everything we would tell a client about architecture decision records in the time it takes to drink a coffee.

Most systems fail at the seams rather than inside any one component. If two people in the business would answer this differently, that gap is the actual problem.

What it costs to ignore

Record the decision, the alternatives, and why they were rejected. None of that requires a large budget, only a decision and someone to own it. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

How to approach it

The reasoning is what future teams actually need. Getting it slightly wrong is survivable. Ignoring it entirely is not. It rarely shows up as a line item, which is exactly why it slips.

Where it usually goes wrong

A short record beats a long document nobody opens. Getting it slightly wrong is survivable. Ignoring it entirely is not. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

The short version

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. Three things worth confirming about architecture decision records before you move on:

• Someone can say what the current setup is without going to look
• The reasoning is what future teams actually need — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Worth checking on your own setup before it becomes someone else's problem to fix.