What to ask your agency about architecture decision records

This is cheap to get right at the start and expensive to retrofit. If you are briefing an agency or a freelancer on architecture decision records, these questions are worth asking early.

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. Write the reasoning down alongside the decision, because the reasoning is what changes first.

Questions worth asking

• Who will actually do this work, and have they done it before?
• How will we know afterwards whether it worked?
• What happens if it needs changing in a year?
• What are you assuming that we have not confirmed?

What a good answer sounds like

Record the decision, the alternatives, and why they were rejected. Small and consistent beats large and occasional here. It rarely shows up as a line item, which is exactly why it slips.

A short record beats a long document nobody opens. That sounds obvious written down. It is still the thing most often skipped. Budget a little time for it every quarter and it never becomes a project of its own.

What this looks like day to day

Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. 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

If you want a second opinion on how yours is set up, ask.