Don't Let AI Generate Your Spec — Write It by Hand
It is tempting to ask a model to write your whole spec for you. But the specification is the one artifact where the value comes from what only you know — and a model filling it in from general knowledge produces exactly the vague, low-signal requirements that make the whole method fail. The spec is where you should keep your hands on the wheel.
Why Generation Underperforms
A model writing a spec from general knowledge restates things the agent already knows — generic best practices, obvious facts about your framework — adding tokens and noise without signal. It also produces plausible-sounding directives that read well but do not translate into specific behaviour. The result is a bloated, low-signal spec, and a vague spec is worse than none: it looks authoritative while pointing the implementation at the wrong target.
The Value Is in What Only You Know
The worth of a spec is in the things only your team knows: the constraint you adopted after a painful incident, the behaviour that must hold for a non-obvious reason, the acceptance criterion that encodes a real business rule. A model cannot generate what it does not know, so it fills the space with generalities. Writing the spec yourself is not a chore you failed to automate — it is the thinking the whole method exists to force.
Where Automation Does Help
This is not an argument against tools. Let the agent draft a skeleton of sections and detected constraints, which you then fill and prune. Let it interrogate your draft for ambiguity — a good clarify step surfaces questions you had not considered. Let it generate the plan and tasks from your reviewed spec. The dividing line is intent: never let the model invent what the system should do; do let it accelerate everything downstream of that decision.
The Tell
A generated spec reads like it could describe any project; a hand-written one reads like it could only describe yours — a specific constraint, a named edge case, an acceptance criterion that is clearly the scar of a past bug. Aim for that signature: every requirement so particular it could not have been guessed. That specificity is the entire point of writing a spec at all.