Spec-driven development with AI agents

A few years of building with AI coding agents has surfaced a discipline that, in another form, is as old as software engineering: writing the specification first. When a capable agent does the actual implementation, the spec — the precise description of what to build — becomes the highest-leverage artifact in the whole project, because it’s the input that most determines whether the agent produces something good or a confident mess. A clear, complete spec gives the agent what it needs to build the right thing; a vague one sends it wandering, filling gaps with guesses that look plausible and aren’t what you wanted. This is a deep-dive on why spec-driven development has resurged precisely in the agent era, what a good spec for an agent actually looks like, and how the day-to-day workflow changes when the spec, not the code, is the thing you craft.

Why the spec became the leverage point

To see why this matters now specifically, connect it to a shift I’ve written about: with agentic coding, the developer’s job moves from writing code to specifying and directing it. Follow that to its conclusion and the spec stops being paperwork and becomes the primary input — the thing that most determines the output’s quality. The logic is direct:

The agent builds what the spec describes. Its output is only as good as its understanding of what you want, and the spec is where that understanding comes from. Garbage in, garbage out has never been truer — the agent is fast and capable, but it builds what you asked for, not what you meant.
Ambiguity gets filled with guesses. Where the spec is vague or silent, the agent doesn’t stop and ask the way a junior developer might — it guesses, confidently, and produces something plausible that may be entirely wrong. Every gap in the spec is a place the agent will improvise, often in a direction you didn’t intend.
The spec is where your effort now pays off most. Time spent making the spec clear and complete buys more quality than time spent anywhere else, because it’s upstream of everything the agent does. Reviewing and fixing bad output is far more expensive than specifying well in the first place.

So the spec is no longer a formality you write to satisfy a process — it’s the highest-leverage work in the project, the place where clarity translates most directly into good output. This is why a discipline that had faded in fast-moving teams has come roaring back: when an agent implements, specifying well is the engineering.

What a good spec for an agent looks like

A good spec for an agent isn’t a thousand-page requirements document — that’s the old waterfall failure mode, and it’s just as wrong here. It’s a clear, complete, and appropriately precise description of what to build. The qualities that matter:

Clear on the what and the why. State what to build and the intent behind it, so the agent’s inevitable judgment calls in the gaps are anchored to your actual goal rather than made blind. An agent that understands why makes better guesses where the spec is necessarily incomplete.
Explicit about the constraints and the edges. The requirements that matter, the edge cases to handle, the things that must be true. These are exactly what the agent won’t infer correctly on its own, so naming them is high-value. The edge cases you leave out are the ones that come back as bugs.
Concrete where precision matters, loose where it doesn’t. Be exact about the parts where exactness matters — the data shape, the key behaviours, the interfaces — and don’t over-specify the parts where the agent’s judgment is fine. Over-specifying everything is as wasteful as under-specifying the important things; the skill is knowing which is which.
Reviewable on its own. A good spec is something you (and your team) can read and evaluate before any code exists — catching a wrong assumption at the spec stage, where it’s cheap to fix, instead of after the agent has built on it.

The skill of writing these is real and somewhat new: it’s the ability to think clearly about what you actually want and express it precisely enough for an agent to build, without drowning it in detail it doesn’t need. It’s prompt engineering elevated to the level of a whole feature — the same discipline of precise, complete instruction, applied to the spec.

How the workflow changes

Spec-driven development with agents reshapes the day-to-day loop. The shape that works:

Write the spec. Think through and clearly describe what to build, at the right level of precision. This is now the core creative and engineering work — where you decide what should exist and pin it down.
Review the spec — ideally before implementation. Because the spec drives everything, catching problems here is far cheaper than catching them in the generated code. Treat the spec as a reviewable artifact in its own right, scrutinized the way you’d scrutinize a design.
The agent implements from the spec. Hand the agent the spec and let it build, the part that’s now fast.
Review the implementation against the spec. Verify the agent built what the spec described — and, crucially, this review is sharper because you have the spec to check against. “Does this match what we specified?” is a far more tractable review question than “is this code good?” in the abstract.

Two things stand out about this loop. First, the spec becomes a source of truth — when behaviour is in question, you check it against the spec, and when requirements change, you change the spec and re-derive. Second, reviewing against an explicit spec is much more effective than reviewing code cold: the spec gives you the yardstick. This is the same critical-review discipline that agentic coding demands, made easier because you specified what “correct” means up front.

What it doesn’t fix

In keeping with the honesty this series insists on: spec-driven development is a powerful discipline, not a magic wand. A few honest limits. It doesn’t remove the need to review the implementation — the agent can still get the code wrong even against a good spec, and a spec you can’t verify the output against is no protection. It doesn’t mean specs must be exhaustive — over-specification is its own failure, slow and brittle, and the goal is appropriate precision, not maximal. And it doesn’t eliminate iteration — you’ll often refine the spec as building reveals gaps in your own thinking, which is fine and expected; the spec is a living artifact, not a contract carved before any learning happens. Spec-driven development makes the agent dramatically more effective by giving it a clear target; it doesn’t remove your judgment from the loop, it relocates it to where it has the most leverage.

Verdict

When a capable AI agent does the implementation, the specification becomes the highest-leverage artifact in the project, because the agent builds what the spec describes and fills every gap with a confident guess — so a clear, complete spec produces good code and a vague one produces a plausible mess. That’s why spec-driven development has resurged in the agent era: with the developer’s job shifting from writing code to specifying and directing it, specifying well is the engineering. A good spec for an agent is clear on the what and why, explicit about constraints and edge cases, concrete where precision matters and loose where it doesn’t, and reviewable on its own — not an exhaustive requirements document, which is the old failure mode, but appropriately precise. The workflow becomes write the spec, review it before implementation (where fixing problems is cheap), let the agent build, then review the implementation against the spec — which makes the review far sharper, because you have a yardstick. The spec becomes the source of truth. It doesn’t remove the need to review the output, doesn’t require exhaustive specs, and doesn’t eliminate iteration — it relocates your judgment to where it has the most leverage. In the agent era, the clearest thinkers about what to build have the advantage, because the spec is now where quality is won.