What actually belongs in an architecture decision record (and what doesn't)

Short summary

Most ADRs fail because they contain the wrong content — burying the reasoning behind decisions under irrelevant detail. A good ADR captures only irreversible decisions with their conflicting constraints, seriously-considered alternatives, and honest consequences including downsides. ADRs should stay under 600 words, never document unsettled decisions, and never be written retroactively just to satisfy a process checklist.

• •ADRs should capture only costly-to-reverse decisions with fresh reasoning, not design docs or specs
• •Include real constraints in conflict, alternatives seriously considered, and honest negative consequences
• •Avoid retroactive ADRs and over-documenting trivial decisions — both destroy signal-to-noise ratio

Generated with AI, which can make mistakes.