Everyone has had the moment. You ask an AI coding agent for a feature, it churns out a confident wall of code, and it's wrong. Not broken-syntax wrong, subtly wrong. It solved a slightly different problem, ignored a constraint you thought was obvious, or invented an architecture nobody asked for. So you nudge it, it rewrites half of it, breaks something else, and an hour later you're wondering whether you'd have been faster just typing the thing yourself.
That loop has a name now: vibe coding. You describe a vibe, the agent guesses, you both muddle toward something. It's great for a weekend toy and genuinely risky for anything real. And the fix that's caught on in 2026 is almost boringly old-fashioned: write the spec first.
The actual problem isn't the AI
Here's the thing worth sitting with. When an agent builds the wrong feature, it usually isn't because the model is weak. As GitHub put it when they introduced their toolkit, these agents are exceptional at pattern completion, but not at mind reading. Give a literal-minded, tireless colleague a vague instruction and they'll fill every gap with an assumption. A vague prompt hides a thousand unstated decisions, and the agent has to guess all of them.
Spec-driven development, or SDD, removes the guessing. The idea: an executable, version-controlled specification, not the code, becomes the single source of truth. You write down what the system should do, in detail, and only then does anyone (human or agent) write code against it.
GitHub Spec Kit and why this took off
The concept isn't new. Specs have been around as long as software. What changed is that AI agents made the payoff enormous, because a good spec is exactly the kind of explicit, unambiguous intent an agent thrives on.
GitHub open-sourced a toolkit called Spec Kit in late 2025, and it turned SDD from a philosophy into a workflow you can actually run. It's an MIT-licensed framework that's grown to well over a hundred thousand GitHub stars, and it works across more than thirty agents including Claude Code, Copilot, Cursor, Gemini CLI, and others. You install a small CLI and drive the whole thing with slash commands.
Getting started looks like this:
uvx --from git+https://github.com/github/spec-kit.git specify init my-project
From there you use commands like /specify, /plan, and /tasks to walk the agent through each stage instead of dumping one big request on it.
The pipeline, stage by stage
The heart of SDD is a simple sequence. Each stage produces a written artifact the next stage builds on.
- Constitution. The non-negotiable principles for the whole project. Testing standards, architectural rules, how the codebase is allowed to be structured. This is the frame everything else has to respect.
- Specify. You describe the goals: user journeys, what success looks like, what the thing is for. Crucially, this stage is about the what and why, not the tech stack. The agent drafts a detailed spec and you refine it until it matches what's in your head.
- Plan. Now the how. You bring in the architecture, the stack, the constraints, your company's standards, and the agent produces a technical blueprint that fits them.
- Tasks. The agent breaks the spec and plan into small, testable, reviewable chunks, each solving one specific thing. No more thousand-line pull requests.
- Implement. The agent works through the tasks one at a time, and you review focused changes rather than a giant code dump you have no hope of reading properly.
Notice where the human effort sits. You spend real energy in the constitution, specify, and plan stages, settling intent before any code exists. That's the whole trick. Disagreements surface in a document, where they're cheap to fix, instead of in code, where they're expensive.
Vibe coding vs spec-driven, honestly
Neither is universally right. It's about matching the method to the stakes.
| Vibe coding | Spec-driven development | |
|---|---|---|
| You give the agent | A vague prompt | An agreed, written spec |
| Intent is settled | While coding (or never) | Before coding starts |
| Review unit | A big blob of code | Small, testable tasks |
| Best for | Prototypes, throwaways, exploring | Real features, teams, anything you maintain |
| Main risk | Confidently wrong output | Up-front time on the spec |
| Reported effect | Lots of rework | Community reports 60 to 80% fewer rework cycles |
Those rework numbers come from the community rather than a controlled study, so take the exact figure with a pinch of salt. The direction, though, matches what most people feel once they try it: you spend more time before the code and dramatically less time after it.
When to reach for it, and when not to
SDD shines when getting it wrong is expensive or when more than one person has to live with the result. Three cases where it earns its keep:
- Greenfield projects, where a spec makes sure the agent builds your actual vision instead of a plausible-looking substitute.
- Feature work in an existing system, where the spec keeps new code consistent with what's already there.
- Legacy modernisation, where writing the spec is how you capture the original business logic before you rebuild it.
And when to skip it? If you're spiking an idea to see if it's even worth doing, a full constitution-to-tasks pipeline is overkill. Vibe your way to a throwaway prototype, learn what you needed to learn, then write the spec if the idea survives. The mistake isn't using one or the other. It's using vibe coding for something you'll have to maintain for three years.
The bigger point
Spec-driven development is really a management idea wearing an engineering hat. It says the bottleneck was never typing speed, it was clarity of intent, and AI agents make that painfully obvious because they'll execute your ambiguity at full speed and full confidence.
For teams adopting AI coding tools, this is the habit that separates the ones who ship reliable software from the ones stuck in an endless rewrite loop. Slow down at the start, write the thing down, get agreement, and let the agent do what it's genuinely great at: turning a clear specification into working code, fast. Boring, and it works.