Architecture decision records that actually get read

Architecture decision records fail in two ways. Either they aren't written, or they are written as justifications after the fact: a paragraph explaining why the thing that was chosen was obviously right. Neither helps the engineer eighteen months later who needs to know whether the reason still holds.

The eight fields

• Decision: what are we choosing? One sentence.
• Why: what problem does it solve? Link to the problem, not the technology.
• Evidence: what supports it? Graded: fact, assumption, hypothesis, constraint.
• Alternatives: what else could we have done, including nothing?
• Why not: why was each alternative rejected? This is the field that gets read most.
• Trade-offs: what are we accepting? Who bears it?
• Reversibility: how hard is it to change later, and what would trigger a revisit?
• 5 Whys: the short chain from this decision back to the business reason.

The rule about assumptions

Every assumption in the evidence section should say what would make it false and what happens if it is. Most decisions that go wrong do so because an assumption changed and nobody was watching it. Listing the assumptions with their consequences turns the ADR from a historical document into a monitoring checklist.

Keep it to a page

A decision record longer than a page is a design document with a decision hidden in it. Put the design elsewhere and link to it. The record exists to answer one question quickly: why did we do this, and does that reason still apply?