Spec-first building: why you write the doc before the code

Spec-first building means writing a short, plain description of what you’re about to build — the problem, the proposed fix, what’s out of scope, how you’ll know it worked — before you or Claude write any code. It feels like a slower start. It isn’t, once you count the rebuilding you skip.

The reason this matters more with Claude Code in the picture, not less: a model will happily start building from a vague idea, filling gaps with plausible-sounding assumptions instead of asking you to clarify. A spec forces those gaps to surface while they’re still a sentence to fix, instead of a feature to unbuild after it’s shipped.

A working spec doesn’t need to be long. One paragraph on the problem, one on the solution, a short list of what’s explicitly out, and three to five acceptance criteria you could actually check against a shipped feature. If a “spec” is longer than a page, it’s probably trying to also be documentation, a pitch, and a spec at once — split those apart.

See the PRD playbook for the exact prompt to turn a rough idea into one of these.