Design Documents

Decision records that explore problems and commit to solutions before implementation. A design document serves three purposes:

1. Thinking tool. Writing forces the author to plan before coding — understanding the problem, evaluating options, and committing to a direction.
2. Review artifact. A deliverable others can evaluate before implementation starts, catching design flaws when they cost minutes to fix, not days.
3. Decision record. Preserves what was decided and why — an architecture decision record (ADR) that future readers can reference without re-doing the analysis.

The deliverable must be equally useful to a person reading it and to an agent consuming it to plan implementation.

When to Write

Write a design doc when 3+ of these apply: