Key Takeaway
Spec-first AI coding flips the usual order: before the agent writes a line, it interviews you, turning vague requests into a written spec you approve. That spec becomes the contract the agent builds and tests against, catching misunderstandings while they are still cheap words instead of expensive code.
The fastest way to get the wrong feature from an AI agent is to describe it in one line and say go. The agent fills every gap you left with a guess, writes hundreds of confident lines on top of those guesses, and you discover the mismatch only when you read the result.
Spec-first coding front-loads the disagreement. Instead of prompting once and hoping, you make the agent interview you until the requirement is pinned down in writing. This guide walks through running that interview, turning the answers into a spec, and handing that spec to a fresh session to build.
Why the interview comes first
A one-line prompt is an under-specified contract, and the agent resolves the ambiguity in the direction of whatever is easiest to generate. The gap between what you meant and what you said does not disappear; it gets baked into code, where it is far more expensive to find and remove.
Making the agent ask questions moves that gap to the front, where it is cheap to fix:
- Every clarifying question is a decision surfaced before it becomes a line of code.
- You correct a misunderstanding in a sentence instead of in a refactor.
- The written answers become a shared reference both you and the agent can point back to.
Run the interview
Start by telling the agent explicitly not to write code yet. Its job is to ask, one focused batch of questions at a time, about scope, edge cases, data shapes, and how you will know the feature works. A good opening prompt makes questioning the agent's only allowed move.
The opening instruction can be as plain as this:
Do not write any code yet.
Your only task right now is to interview me until you can write a
clear spec for this feature. Ask your highest-value questions first,
in small batches, about scope, edge cases, data shapes, and how we
will know it works. When you have enough, write SPEC.md and stop.Cap the interview. Tell the agent to ask its highest-value questions first and to stop once it has enough to write the spec. Left fully open-ended, some agents will interrogate you forever; the goal is a good-enough spec, not a perfect one.
Turn answers into a spec
Once the questions are answered, have the agent write the spec to a file such as SPEC.md and read it back critically. A useful spec is short and testable:
- A one-paragraph statement of the goal and who it is for.
- Explicit scope: what is in, and just as important, what is out.
- Acceptance criteria phrased so that a test could check each one.
- Known constraints, data shapes, and any decisions made during the interview.
Build against the spec in a fresh session
Hand the approved spec to a new session with a clean context. The interview transcript is noise now; the spec is the signal. Starting fresh keeps the build focused on the agreed contract instead of the meandering path that produced it.
Because the spec names its own acceptance criteria, the agent can check its work against them and you can review the change against the same list. The spec that started as an alignment tool becomes the test plan and the review checklist for free.
A spec is a snapshot, not a cage. When the build reveals that a decision was wrong, update the spec and note why, then continue. A spec you quietly diverge from is worse than none, because it now lies about what the code is supposed to do.
When spec-first is worth it
The overhead of an interview pays back on ambiguous or high-stakes work, and gets in the way on trivial ones:
- Worth it for a new feature with unclear requirements, where a wrong guess costs a day of rework.
- Worth it for anything a teammate will inherit, since the spec doubles as documentation of intent.
- Skip it for a quick fix or an exploratory spike, where writing a spec costs more than just trying the change.
Spec-first coding trades a few minutes of questions for hours of avoided rework. Tell the agent to interview you, capture the answers in a short testable spec, and build against it in a clean session. The discipline is simple: agree on what done means in words before the agent spends tokens getting there.