Spec-Driven Development: The New Unit of Work

Every serious AI coding tool now ships the same feature, and almost nobody has noticed what it means.

GitHub released Spec Kit, an open-source toolkit that crossed seventy-two thousand stars. Amazon built an entire agentic IDE called Kiro around the idea. Claude Code, Cursor, OpenSpec, BMAD, Tessl, and Google Antigravity each shipped their own flavor. DeepLearning.AI put out a short course on it. And at the AI Engineer World’s Fair, an OpenAI researcher named Sean Grove stood on stage and said the quiet part out loud: code is a lossy projection of intent, and the best coder will soon be the best communicator. The feature they all shipped is spec-driven development, and the phrase spreading through every builder thread is the same three words: the spec is the prompt.

Strip away the tool names and the conference talks, and here is the durable claim underneath the noise. For seventy years, code was the thing you kept and the specification was the thing you threw away. You wrote a doc to line up the team, then you wrote the real artifact, the code, and the doc rotted in a wiki nobody opened again. That arrangement is now inverted. When a model can generate a working implementation in seconds, the code becomes the cheap, regenerable, disposable part, and the specification becomes the asset you actually own.

The unit of work moved up one level. It used to be the commit. It is now the spec. I run two companies where AI writes most of the code, and the single change that moved my output more than any model upgrade was learning to treat the spec, not the code, as the thing worth getting right. This is the map for why that works, and how to do it.

Table of Contents

• The Problem: Vibe Coding Hit a Wall Called Drift
• The Great Inversion: Code Was the Asset, Now the Spec Is
• The Specification Gap: Where Drift Is Actually Born
• The Spec Quality Ladder: From Vibe Prompt to Self-Checking Spec
• Anatomy of a Spec an Agent Can Execute
• What Actually Changes for a Solo Founder
• Spec Smells: The Ambiguities That Become Bugs
• The Contrarian Take: Specs Are Not a Silver Bullet
• What to Do Monday Morning
• FAQ: Spec-Driven Development

The Problem: Vibe Coding Hit a Wall Called Drift

The reason spec-driven development exists is that the thing before it stopped scaling.

For about two years, the dominant way to build with AI was what people started calling vibe coding: describe what you want in a sentence or two, let the model generate, eyeball the result, nudge it, repeat. It is intoxicating at first. Garry Tan, who runs Y Combinator, reported that for a quarter of the Winter 2025 batch, ninety-five percent of the lines of code were written by AI. Not a typo, he said. The age of vibe coding is here.

Then the bill arrived. The failure mode of vibe coding is not that the model writes broken code. It is worse than that. The model writes plausible code that quietly solves the wrong problem, and it does it confidently. The industry has a word for this now: drift. The agent fills every gap in your request with a guess, the guesses accumulate, and forty files later you have a working application that does something adjacent to what you meant. Nobody grounded the work in a real description of the target, so the target moved.

The data on what that produces is not subtle. Veracode ran eighty coding tasks across more than a hundred models in 2025 and found that forty-five percent of AI-generated code contained a security vulnerability. AI-written code carried 2.74 times more vulnerabilities than human-written code. Eighty-six percent of samples failed to defend against cross-site scripting, and eighty-eight percent were open to log injection. GitClear, which measures code churn across millions of commits, found that refactoring collapsed from around twenty-four percent of changes to under ten percent, duplicated code blocks rose roughly eightfold in a single year, and the average developer now checks in seventy-five percent more code than a few years earlier. More code, less structure, more repetition. That is the signature of generation without a plan.

Here is the part that has been true since long before AI, and explains why drift is so expensive. The cost of fixing a defect climbs the later you catch it. The IBM Systems Sciences Institute put numbers on this decades ago: a defect that costs one unit to fix at design costs about fifteen units at testing and sixty to a hundred units once it reaches production. A hundred-dollar fix in the requirements becomes a ten-thousand-dollar fix in production. NIST found production defects cost roughly thirty times more than early ones, and up to sixty times more when they are security defects. The reason is mechanical. When a mistake lives in a description, fixing it means editing text. When it lives in code, fixing it means editing code and retesting. When it reaches customers, fixing it means editing, retesting, redeploying, running the incident, and cleaning up the secondary damage.

AI did not repeal that curve. It bent the front of it. Generating code is nearly free now, so the expensive part is no longer typing. The expensive part is discovering, three hundred generated lines later, that you and the model never agreed on what good looked like. Vibe coding pushes every ambiguity downstream to the most expensive place to catch it. Spec-driven development pulls it back upstream to the cheapest.

The Great Inversion: Code Was the Asset, Now the Spec Is

To see why the spec became the unit of work, look at what changed about the cost of code.

In the old arrangement, code was the scarce, expensive, hand-built artifact, so code was the source of truth. The specification was scaffolding. You wrote it to align people, maybe to get a budget approved, and then you built the real thing. Six months later the code and the doc disagreed, and everyone knew which one to trust: the code, because the code was what actually ran. Tests and docs were derived from the code, by hand, and they went stale the moment someone shipped a fix under deadline.

Now flip every term. Code is cheap to generate and cheap to regenerate. What is scarce is a precise statement of what the software should do and why. So the specification becomes the durable asset, the thing you version-control and defend, and the code becomes a projection of it. Sean Grove’s line is the cleanest way to say it: code is a lossy projection from the specification. When you keep only the code, you have thrown away the intent and kept the guess. When you keep the spec, you can regenerate the code against a better model next quarter and get a better projection for free.

This is not a metaphor. OpenAI’s own Model Spec, the document that describes how their models should behave, is a living set of markdown files. Because it is written in plain language, people in product, legal, safety, research, and policy can all read it, argue about it, and contribute to it. The spec is the source that compiles down into model behavior, evaluations, and documentation. The implementation is downstream. The company that builds the models treats the specification as the code, and treats the model as a projection of the spec. If that is how the frontier labs run their own most important product, it is worth asking why a solo founder would treat their spec as a throwaway.

The practical consequence is that your competitive position stops living in the code and starts living in the spec. Anyone can generate a login flow. What they cannot generate is your precise understanding of how your specific customer thinks, what edge cases actually matter in your domain, and what good output looks like when the obvious answer is wrong. That understanding is what a real spec captures. The code is just this quarter’s rendering of it. I wrote about how the moat relocates when the model gets commoditized in the piece on surviving model churn, and spec-driven development is the daily-practice version of the same idea: own the layer the model cannot regenerate.

The Specification Gap: Where Drift Is Actually Born

If the spec is the unit of work, then the failures of AI development are failures of specification. To fix them, you have to see exactly where they happen.

Between what you meant and what you wrote, there is a gap. You hold a rich, detailed mental model of the thing you want. You compress it into words. The words are always thinner than the model in your head, because language is lossy and because most of what you know is tacit, the kind of thing you would only articulate if someone asked the right question. That compression loss is the specification gap, and it has always existed. What changed is who reads the spec on the other side of it.

When a competent human engineer read your thin spec, they closed the gap with judgment. They noticed the ambiguity, pattern-matched against a hundred similar systems they had built, and either filled the gap the way you would have wanted or, better, came back and asked. The gap was real, but a person with taste and context absorbed it silently. You could ship a vague spec to a good engineer and get a good result, and you came to believe your spec was better than it was. The engineer was covering for you.

An AI agent closes the same gap differently. It does not have your context and it does not stop to ask. It fills the gap with the most statistically plausible completion, which is a confident guess drawn from the average of everything it has seen. Sometimes the guess is right. Often it is subtly, expensively wrong, and it looks finished, which is what makes it dangerous. The agent will never tell you it was unsure. Gokul Rajaram put the test cleanly: in the agent era, the bottleneck is giving the agent a specification tight enough that it can ship without twelve follow-up questions. A ten-page PRD full of aspiration fails that test. A one-page spec with concrete acceptance criteria passes it. If an agent cannot execute your spec, the spec lacks detail. The agent is a mirror held up to your thinking, and it reflects the gaps you did not know you had.

This reframes the whole skill. The valuable move is no longer writing code, and it is not even writing prose. It is noticing your own ambiguity before the agent does, and closing it on purpose rather than letting a guess close it for you. Every place your spec says fast, or clean, or handle errors gracefully, or make it intuitive, is a place you have handed a decision to the model. The discipline of spec-driven development is the discipline of finding those words and replacing them with a number, an example, or a rule. This is close cousin to the craft I described in the context engineering playbook: context engineering is what you feed the agent at runtime, and specification is what you decide before runtime. Both are about removing the model’s need to guess.

The Spec Quality Ladder: From Vibe Prompt to Self-Checking Spec

Not all specs are equal, and the difference is measurable. Early adopters at GitHub and AWS reported that spec-first work produced roughly three to ten times higher first-pass success on non-trivial tasks, meaning the agent got it right without a from-scratch redo. GitHub said internal teams using Spec Kit shipped features with an order of magnitude fewer regenerate-from-scratch cycles. AWS documented customer cases where a feature that would have taken forty hours shipped in under eight hours of human time when it was authored as a spec first. The variable that moves those numbers is how much of your intent you actually wrote down. That is a ladder, and most people are standing on the bottom rung without knowing there are higher ones.

Rung zero is the vibe prompt. Build me a dashboard that shows sales. It feels efficient and it is fine for a throwaway prototype, but every real decision is delegated to the model. What counts as sales? Over what period? For whom? Refreshed how often? The agent will answer all of those, invisibly, and you will discover its answers by being surprised.

Rung one is the aspirational PRD, and it is a trap because it looks like rigor. Ten pages of goals, personas, and hopes, written in the language of persuasion rather than instruction. It was built to win a meeting, not to be executed. An agent handed a rung-one document has more words to misread and still no concrete target, so it produces confident, elaborate drift.

Rung two is a structured spec: a clear problem statement, an explicit scope with things named as out of scope, and a description of the intended user experience. This is where most good product thinking already lives, and it removes whole categories of misunderstanding.

Rung three is an executable spec. It adds the things that make intent unambiguous to a machine: acceptance criteria phrased as conditions that are either met or not, concrete input and output examples, and the interfaces the code must conform to. At this rung the agent stops asking and starts shipping, because you have answered the questions before it needed to ask them.

Rung four is a spec paired with evaluations. The acceptance criteria are written as checks the agent can run against its own output, so the loop closes without you in it. The spec does not just describe the target, it lets the agent verify whether it hit the target. This is where spec-driven development meets the reliability work I covered in the AI eval budget: an eval is just the executable half of a good spec. Climbing from rung zero to rung four is the entire game, and each rung up buys you first-pass success you would otherwise pay for in rework.

Anatomy of a Spec an Agent Can Execute

Knowing the ladder exists is not the same as being able to write a rung-three spec. So here is the anatomy, section by section, with the drift each part is designed to kill. This is a synthesis of what shows up in the tools that work, from GitHub Spec Kit to Kiro to Gokul Rajaram’s product-spec format, reduced to what actually earns its place on the page.

The order matters as much as the contents. The problem comes first because everything else is downstream of it, and a spec that starts with a solution has already skipped the most important decision. Non-goals come early because naming what you are not building removes more ambiguity per sentence than almost anything else you can write. Acceptance criteria are the load-bearing section, and the test of a good one is that two different people, or a person and an agent, would agree on whether it was met without arguing. If the criterion contains the words fast, clean, intuitive, or seamless, it is not a criterion, it is a wish, and the agent will grant it however it likes.

Notice what this document is not. It is not ten pages. Gokul Rajaram’s whole argument for retiring the classic PRD is that length is not rigor, and a one-page spec with real acceptance criteria beats a ten-page narrative every time, because the agent, and the human, can hold the whole thing in view and act on it. The goal is not to write more. It is to write the few things that remove the most guessing, and to stop. A tight spec is a compression of judgment, not a dump of context.

There is a second-order benefit that surprised me the first time I felt it. Writing the spec this way teaches you how much of your own standard you had never articulated. You sit down to write the acceptance criteria for a feature you understand deeply, and you discover you cannot state, in a way a machine could check, what separates a good result from a bad one. That discovery is not a failure of the exercise. It is the exercise. The gap you find on the page is the gap that would otherwise have become a bug, and you found it while it still cost a hundred dollars instead of ten thousand.

What Actually Changes for a Solo Founder

The abstract case for specs is easy to nod along to and easy to ignore. The concrete case is where it earns a place in how you work. Three things change, and each of them compounds.

The first change is that your highest-return hour moves upstream. When I was writing code by hand, the return on an hour was roughly linear: one hour of typing produced about one hour of code. Now an hour spent sharpening a spec can direct many hours of generated implementation, and the quality of those hours is set almost entirely by the spec. That is why the return concentrates at the top of the stack. An hour spent removing three ambiguities from a spec is worth more than an hour spent fixing the three bugs those ambiguities would have caused, because the fix is a projection you can regenerate and the spec is the source you keep. This is the same shape as the argument in loop engineering: the moat is not the model or the individual generation, it is the repeatable loop you build around it, and the spec is the instruction the loop runs on.

The second change is that the spec becomes your onboarding document for both agents and humans, which means writing it once pays you many times. When a new agent, a new model version, or a new contractor picks up the work, the spec is what carries the context to them. Sean Grove’s point about the OpenAI Model Spec applies at any scale: because it is written in plain language, everyone can read, debate, and contribute to the same source. A solo founder who keeps real specs has, without meaning to, built the thing every growing company struggles to build, which is a written record of why the software is the way it is. I argued in the AI adoption paradox that the individual wins because they are the integration, holding knowledge, authority, and execution in one head. The spec is how you get that context out of your one head and into a form an agent can act on without you in the room. It is the artifact that lets you stay small and still not be the bottleneck.

The third change is that specs make your judgment portable across model churn. Models get deprecated, repriced, and replaced faster than any other part of your stack. If your value lived in prompts tuned to one model’s quirks, that value evaporates on the next deprecation. If your value lives in a clean specification of what the software should do, you point the next model at the same spec and get a better result. The spec is the part of your work that does not expire. In a world where the underlying models change every few months, owning a durable statement of intent is worth more than owning any particular clever implementation, because the implementation was always going to be temporary and now you have finally admitted it.

The uncomfortable flip side is that this is a real skill shift, and not everyone will make it. The best builder in the spec era is the one who can think clearly about what they actually want and state it precisely, which is a different muscle from the one that makes someone good at writing clever code. Grove’s blunt version is that the best coder will soon be the best communicator. That is good news for founders, who have always had to be communicators, and it is a warning for anyone whose entire identity was speed at the keyboard. The bottleneck moved, and it moved toward clarity of thought.

Spec Smells: The Ambiguities That Become Bugs

The fastest way to get good at this is to learn to smell the ambiguities in your own drafts, the same way an experienced engineer smells bad code. Here are the most common spec smells I catch in my own writing, what an agent does with each one, and the fix. Every one of these is a place where a vague word silently became a decision.

The pattern under all six is the same. Every adjective is a deferred decision, and every deferred decision gets made by the model at the moment it is cheapest for the model and most expensive for you. The word gracefully is not an instruction, it is a hole in the shape of an instruction, and the agent will fill it with concrete behavior you never chose. When I review my own specs now, I read them looking for exactly these words, and each time I find one I ask a simple question: if I do not answer this, the model will, so do I want to own this decision or gamble it? Most of the time I want to own it, and answering takes thirty seconds. That thirty seconds is the highest-return work in the whole build.

This is also why spec-driven development is not the same as writing more documentation. Documentation describes what the code does after the fact. A spec decides what the code will do before it exists, and it does so in language precise enough that a machine cannot wriggle out of it. The test is executability. If you handed your spec to an agent with no other context, would it build the right thing, or would it have to guess? If it would guess, you have a document. If it would ship, you have a spec.

The Contrarian Take: Specs Are Not a Silver Bullet

Here is where I break from the loudest voices selling spec-driven development, because the pendulum is swinging too far and the oversell will produce its own backlash.

The strongest version of the SDD pitch quietly reinvents the waterfall model, the discredited idea that you can specify a whole system up front and then build it in one clean pass. That idea failed for a permanent reason: for anything genuinely new, you do not know what you want until you have seen a version of it. Requirements are discovered by building, not just before building. A founder who spends three weeks perfecting a spec for a product nobody has touched is doing the same thing as a founder who spends eighteen months polishing an MVP. Both are avoiding contact with reality and calling it rigor. Over-specification is a real failure mode, and it is the one that spec evangelism will cause.

So the honest position is narrower and more useful than the pitch. Match the spec to the stakes. For a throwaway prototype whose entire purpose is to learn what you want, a vibe prompt is correct, and writing a formal spec first is waste. The value of the prototype is the discovery, and you should generate fast, learn, and throw it away. But the moment code crosses from disposable to load-bearing, the moment other people or real money depend on it, the calculus flips hard, and the cost curve from the IBM and NIST data takes over. The right sequence for anything new is to vibe-code a prototype to find the shape, then write the spec once you know it, then generate the real thing against that spec. The mistake is not skipping the spec. The mistake is skipping the spec on the thing that ships.

There is a second trap worth naming. A spec is not a guarantee, and treating it as one is how careful teams still ship bad software. The agent can satisfy every acceptance criterion you wrote and still produce something wrong, because your criteria were incomplete, which they always are. The spec reduces drift, it does not eliminate the need for judgment at the end. Anyone selling specs as a way to remove the human from the loop is selling the same fantasy the vibe coders sold, just dressed in more responsible clothing. The spec moves your judgment to a better place in the process, earlier and more explicit, but the judgment is still yours. The data on this is quiet but clear: developers report that AI improves their code quality, while the objective churn and vulnerability numbers move the other way. That gap between how good it feels and how good it measures is exactly the gap a spec is supposed to close, and it only closes if you keep reading the output with a skeptical eye.

What to Do Monday Morning

None of this matters until you change what you do before you generate code. Here is the sequence I would run, starting with your next real build.

Pick your next non-trivial feature and do not prompt for it yet. Before you type a word to the agent, open a blank page and write the spec. Give yourself twenty minutes and the six sections from the anatomy above: problem and intent, scope and non-goals, acceptance criteria, examples and interfaces, constraints and failure modes, checks. If twenty minutes is not enough, that is a signal the feature was less understood than you thought, and you just found that out for free.

Hunt the adjectives. Read your draft and circle every word that defers a decision: fast, clean, intuitive, gracefully, seamless, simple, secure, scalable. For each one, replace it with a number, a concrete example, or an explicit rule. This single pass is where most of the first-pass-success improvement comes from, and it takes about ten minutes.

Write one acceptance criterion as an eval. Take the most important thing that must be true about the output, and phrase it as a check the agent can run against its own work. Even one closes part of the loop and teaches you the shape of the higher rungs. This is the bridge from a spec that describes to a spec that verifies.

Generate against the spec, then diff intent against output. Hand the spec to the agent, let it build, and then compare what it produced against what you specified, criterion by criterion. Where they disagree, decide whether the code was wrong or the spec was incomplete. Usually it is the spec, and you fix the spec, not just the code, so the fix survives the next regeneration.

Version-control the spec, not just the code. Put the spec in the repository next to the code it generated, and when requirements change, change the spec first and regenerate. Within a few builds you will notice the spec has become the thing you actually reach for when you want to understand the system, and the code has quietly become what it always should have been: an output. If you want the fuller reliability layer that sits under this, the guide to why AI agents fail in production covers the failure modes a good spec is designed to prevent, and the AI opportunity map puts the whole builder-craft stack in one place.

FAQ: Spec-Driven Development

What is spec-driven development?

Spec-driven development is a way of building software where a clear, version-controlled specification, not the code, is the source of truth. You first write a precise description of what the system should do, including scope, acceptance criteria, and examples, and then an AI coding agent generates the implementation from that spec. The code becomes a regenerable projection of the spec rather than the primary artifact. It emerged in 2025 as a response to the drift and rework that pure prompt-based, or vibe, coding produced at scale.

Why is the spec now called the new unit of work?

Because the economics of code changed. When code was expensive to write by hand, the code was the asset and the spec was disposable scaffolding. When a model can generate working code in seconds, the code becomes cheap and regenerable, and the scarce, durable artifact is a precise statement of what the software should do and why. The highest-return hour of work moved up a level, from writing the commit to writing the spec that directs many commits, so the spec becomes the unit you plan around, version, and defend.

How is spec-driven development different from vibe coding?

Vibe coding means describing what you want in a sentence or two and iterating on whatever the model generates. It is fast and fine for throwaway prototypes, but it defers every decision to the model, which fills the gaps with confident guesses that accumulate into drift. Spec-driven development front-loads those decisions into an explicit specification with concrete acceptance criteria, so the agent has no gaps to guess at. Early adopters at GitHub and AWS reported roughly three to ten times higher first-pass success on non-trivial tasks when working spec-first.

What makes a spec good enough for an AI agent to execute?

A good spec can be handed to an agent with no other context and still produce the right thing without follow-up questions. In practice that means a clear problem statement, explicit non-goals, acceptance criteria phrased as conditions that are either met or not, concrete input and output examples, named constraints and failure modes, and a way to check the result. The test is executability: if the agent would have to guess to proceed, the spec is incomplete. If it could ship, the spec is done. Length is not the measure; a tight one-page spec usually beats a ten-page narrative.

Does spec-driven development slow you down?

For load-bearing work it speeds you up, because the time you spend on the spec is far less than the time you would spend fixing the bugs that ambiguity produces. The classic defect-cost data shows a fix that costs one unit at the design stage costs sixty to a hundred units in production, and AI generation pushes ambiguity toward that expensive end unless a spec pulls it back. For a genuine throwaway prototype whose only purpose is to discover what you want, skip the formal spec and vibe-code it. Match the rigor to the stakes.

Which tools support spec-driven development?

By 2026 most serious AI coding tools shipped a spec-driven flavor. GitHub released Spec Kit, an open-source, model-agnostic toolkit that crossed seventy-two thousand stars. Amazon built Kiro, an agentic IDE where spec, plan, tasks, and code live in one workspace. Claude Code, Cursor, OpenSpec, BMAD, Tessl, and Google Antigravity added their own versions. The tools differ in workflow, but they share the same core move: write and maintain the specification as the primary artifact, and treat the generated code as downstream of it.

Is spec-driven development just the waterfall model again?

It rhymes with waterfall, and that is the main risk to avoid. Waterfall failed because you cannot fully specify something new before you have seen a version of it; requirements are discovered by building. Spec-driven development works best when you use it after a quick prototype has taught you the shape of the thing, not as a way to plan an entire unknown system up front. Over-specifying an unproven idea is as much a failure as under-specifying a shipping one. The discipline is to specify what you have learned, generate, learn more, and update the spec, not to freeze everything in advance.

Does a spec remove the need to review AI-generated code?

No. A spec reduces drift and raises first-pass success, but it does not eliminate the need for judgment, because your acceptance criteria are always somewhat incomplete. An agent can satisfy every criterion you wrote and still be wrong in a way you did not think to check. Security data underlines this: a large share of AI-generated code ships with vulnerabilities even when it appears to work. The spec moves your review to a better place, earlier and more explicit, and it makes review faster because you can check output against stated criteria. It does not let you leave the loop.

I write one deep playbook like this every day at the intersection of AI, entrepreneurship, and personal growth. If this one changed how you plan your next build, the AI opportunity map is the parent guide, and the production gap is the sibling piece on why so much AI work never ships even when the code runs.