Write the Spec First, Then Let It Move

Spec first prevents scope creep and miscommunication. Ten minutes of spec saves hours of rework.

The last chapter told you to hold the scope; this chapter turns scope into a spec AI can actually use. The biggest source of vibe coding rework is AI diving in to write before it knows what you want. Spec first plugs that source.

After reading, you should be able to answer:

What's the difference between a spec and a prompt?
What must a usable spec clearly include?
Who proposes the first draft: you or the AI?
How long do you spend writing a spec?

Spec vs prompt

It's a hair away, not a world away: a prompt is a one-off message; a spec is a long-lived contract. Write the spec into a project file (AGENTS/CLAUDE) and AI reads it in every later turn, so you don't re-explain from scratch each time.

Want to stop "AI keeps misunderstanding the requirement" → put it in the spec
Want to stop scope creep → put it in the spec
Want consistency across conversations and sessions → put it in the spec

A spec isn't a school essay; it's the project manual for AI: scope, constraints, completion criteria, written through once anthropic-sdlc.

What a usable spec must cover

For whom, solving what problem: one-line position
Scope / not-doing list: what you won't touch, made explicit
Acceptance criteria: what counts as done, specific enough to check
Constraints: tech stack, directory layout, naming, API boundaries
Special rules: the mistakes the model tends to make, banned in advance

Self-check from the model's seat: could it do the job to your standard by reading only this spec? If not, fill in the gaps.

Let the AI propose, don't hand it a draft

There is a counter-intuitive order when you write a spec: don't write your thoughts into a draft and hand it over — let the AI propose first. Come in with a draft and the model tends to agree with you; let it propose and you get to see a real second opinion.

One step comes before the proposal: let it interview you. One or two questions at a time, aimed at your assumptions and the failure modes you have not thought about. The finer its questions, the more likely it actually understood the problem; if it has none to ask, you probably did not explain it clearly.

Then the blind spots. Your version already carries your assumptions, and if it edits from there, your blind spots become the design's blind spots unchanged. Its proposing also tests whether it understood your problem at all — a wrong proposal means you didn't explain it clearly, which is far more useful than it politely revising your draft.

One habit worth copying when you argue back: a correction has to come with a file. Point out that it is wrong and hand over the file that proves it, and what changes is its model of the system. Say only "this part is wrong" and what changes is usually its apology — the next round makes the same mistake in the same place.

When the exception applies: you have thought the constraints through and only want it filled in. But "I only want details filled in" and "I haven't thought this through yet" are easy to confuse, so when you're unsure, treat it as the latter aase-egm.

How long to write

Don't chase perfection. Ten minutes to a usable spec beats forty minutes of polishing when it gets you to something runnable faster.

Big projects, high risk: go slower, write finer
One-off prototypes, demos: coarse is fine, just enough

The point is "have a version first," then iterate as the project moves. The one discipline: don't start building until the spec exists.

There is a hard test for "enough": is this spec clear enough that the code should be able to write itself? At that point every remaining disagreement is an execution detail, and handing it to the model will not send it off course. Start before that point and the undecided judgments become decisions it makes for you mid-sentence, ending up buried in a change nobody designed. When you're unsure, what's missing is usually not more words — it's a question you have not answered yet.

Next: make done machine-checkable

Now that the scope is in a spec, the next step is making "done" machine-checkable instead of a gut call.