A practical checklist for architecture decision records

This is cheap to get right at the start and expensive to retrofit. Run through this the next time architecture decision records comes up.

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. The version that survives contact with a real deadline is the simple one.

The checklist

• Record the decision, the alternatives, and why they were rejected
• The reasoning is what future teams actually need
• A short record beats a long document nobody opens
• Someone is named as the owner
• There is a date to review it again

Why it matters

Record the decision, the alternatives, and why they were rejected. Small and consistent beats large and occasional here. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

How to tell if yours is fine

Most systems fail at the seams rather than inside any one component. Three things worth confirming about architecture decision records before you move on:

• Someone can say what the current setup is without going to look
• Record the decision, the alternatives, and why they were rejected — and you know whether that is true here
• There is a way to tell whether the last change to this helped

None of this needs a rewrite. Most of it is a morning's work once someone decides to do it.