Software Development
Spec-First AI Coding: Let the Agent Interview You
August 20268 min read
It is a workflow where the AI agent interviews you and writes an agreed spec before it writes any code. The spec captures scope, edge cases, data shapes, and acceptance criteria, then serves as the contract the agent builds and tests against, so alignment happens in words before it becomes code.
A one-line prompt leaves gaps the agent fills with guesses, and those guesses get baked into code that is expensive to fix. Making the agent ask questions first surfaces each decision while it is still a cheap sentence to correct, instead of a refactor you discover only after reading the result.
Keep it short and testable: a one-paragraph goal and its audience, explicit scope for what is in and out, acceptance criteria phrased so a test could check each one, and any known constraints, data shapes, or decisions made during the interview. If a criterion cannot be tested, rewrite it until it can.
It works best to hand the approved spec to a fresh session. By then the interview transcript is noise, and the spec is the signal. A clean context keeps the build focused on the agreed contract rather than the meandering path that produced it, which reduces drift.
Skip it for quick fixes or exploratory spikes, where writing a spec costs more than simply trying the change. It pays off on new features with unclear requirements and on anything a teammate will inherit, since the spec then doubles as documentation of intent and as a review checklist.
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.
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:
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.
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:
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.
The overhead of an interview pays back on ambiguous or high-stakes work, and gets in the way on trivial ones:
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.