Spec-Driven Development

Hand an AI a one-line request — "add a way for users to export their data" — and it will cheerfully build something. The trouble is that it had to invent a hundred small decisions you never stated: which format, which fields, what happens to large exports, who's allowed to do it. Some of those guesses will be wrong, and you'll only find out after the code exists.

Spec-driven development fixes this by inserting a deliberate step between the idea and the build: a written spec. The spec is the source of truth — a clear description of the desired behavior that the AI builds against, so the decisions get made on purpose instead of by accident.

A spec isn't a vague paragraph of hopes; it's a concrete description of what the thing should do. What's in scope and what isn't, the key behaviors, the edge cases, the constraints. Its real value shows up in the questions it forces into the open. A good spec doesn't paper over ambiguity — it surfaces open questions so you can answer them deliberately. "What happens when the export is too large to email?" is a cheap question to answer in a spec and an expensive one to discover in shipped code.

This is also why the spec, not the conversation, is the artifact that matters. Once you and the AI agree on the spec, everything downstream has a stable reference to check against — the build either matches the spec or it doesn't, and that's a question you can actually answer.

The flow is short and worth following in order. You start with a rough idea — fuzzy and one-line, the way real features begin. You turn it into a detailed spec, ideally with the AI asking clarifying questions rather than guessing: a question loop where it raises what's unclear, you answer, and the spec tightens with each pass. Once the spec is solid, you break it into user stories — concrete, buildable slices of behavior. Only then does the build begin, with the spec and stories as the reference the AI works against.

The one constant throughout is the human at the review gate. You read and refine the spec before any code is written, because that's the cheapest possible place to catch a misunderstanding. The diagram below traces the whole path: idea into spec, spec into stories, stories into build — with you reviewing the spec at the center of it all.

It's tempting to keep all of this in the conversation — describe the feature, let the AI build, correct it as you go. But chats are a poor home for a source of truth. They grow long, and important decisions get buried under dozens of later messages; they're lossy, as earlier context falls out of the window or gets summarized away; and they're hard to edit, since you can't cleanly revise a decision you made twenty turns ago.

A file has none of those problems. It's stable, it's the whole spec in one place, and you can edit any line of it directly. When you revise the file, you're updating the single artifact everything else builds on — no archaeology through chat history required. This file-based spec is the backbone of the larger AI workflows: the greenfield workflow starts from one, and review gates check work against one. Get the spec right, in a file, and the rest of the process has something solid to stand on.