Architecture decision records for small teams

There is no clever trick in this one, just a handful of decisions worth making deliberately. Most advice about architecture decision records assumes a team that does not exist at your size. Here is the version that does not.

Most systems fail at the seams rather than inside any one component. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

What to keep

Record the decision, the alternatives, and why they were rejected. In practice this is a scheduling problem more than a technical one. The version that survives contact with a real deadline is the simple one.

What to drop

Process that exists to coordinate ten people is overhead when there are two of you. None of that requires a large budget, only a decision and someone to own it.

What good looks like

A short record beats a long document nobody opens. There is a version of this that is over-engineered, and it is worth avoiding. Check it against what you would want a competitor's site to get wrong.

The short version

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
• A short record beats a long document nobody opens — and you know whether that is true here
• There is a way to tell whether the last change to this helped

The point is not perfection, it is knowing which of these you have consciously chosen to skip.