Spec-Driven Development

The structured counterpart to vibe coding: before the agent writes code, you produce a specification -- requirements, design, and a task breakdown -- as an editable, human-readable artifact, and the agent builds against it. The spec captures intent durably so it outlives the chat history and the model's context window.

The Pattern

"I'm sure you've been there: prompt, prompt, prompt, and you have a working application. It's fun and feels like magic. But getting it to production requires more." -- Nikhil Swaminathan & Deepak Singh, Kiro (source)

Spec-driven development inverts the order of vibe coding. Instead of prompting your way to working code and hoping it matches intent, you first produce a specification -- requirements, user stories, a design, and a task breakdown -- as an editable, human-readable artifact, and the agent builds against it. The prompt does not disappear; it gets captured. Intent stops living only in an ephemeral chat history and becomes a durable input the agent, and the next teammate, can work from. Sean Grove pushes this to its conclusion: specifications, not prompts or code, become "the source of truth that compiles to documentation, evaluations, model behaviors, and maybe even code" (Sean Grove, The New Code).

The methodology has crystallized around a wave of tools -- AWS's Kiro, GitHub's Spec Kit, the Tessl Framework -- that turn a one-line request into structured markdown you review and amend before any code is written (Birgitta Böckeler). In Kiro, the same prompt that would trigger scaffolding in "vibe mode" instead generates requirements and a design document you can edit first (RedMonk).

Why It Matters

Vibe coding is fast but "often produces code that doesn't match what you asked for" (Andrew Ng), and there is a chasm between a magical prototype and a deployable system. Spec-driven development front-loads alignment and leaves artifacts that outlive the developer's memory and the model's context window -- so whoever picks the project up later inherits the why, not just a chat log (RedMonk).

It's not a new waterfall

The objection is that it is "just waterfall with an AI doing the typing" -- betting everything on a spec written before you learned anything (John Ferguson Smart). But that is not how it runs. Two things make it a loop, not a one-way handoff:

• Broken down, not written whole. The request is decomposed into a task list you build one slice at a time -- the agent takes a slice until its tests go green, then the next. "The spec isn't a promise the agent makes, it's a test it has to pass... the value is in the feedback loop" (Smart).
• Spec and code, not spec alone. The spec is versioned next to the code and re-read on each prompt, so every feature is built against both the intent and what already runs (Brian Chambers).

That step-by-step grounding is exactly what waterfall lacks.

Examples over format

Format is not the point -- Markdown, Cursor rules, EARS and Agents.md all work, and there is no agreed standard (Birgitta Böckeler). What matters is whether the spec carries concrete examples and acceptance criteria the agent can check itself against. A vague requirement gives it nothing to verify; "turn the examples into acceptance tests the code has to pass" (John Ferguson Smart).

Plan by asking, not just specifying

Good planning interrogates the request before writing the spec -- Spec Kit's /clarify runs "sequential, coverage-based questioning" to cut rework (Spec Kit); the lightest version is a skill that only interrogates, like Matt Pocock's grill-me (mattpocock/skills). How much ceremony you add is a spectrum:

• Light -- the spec is a small composable SKILL.md: a few lines of intent and steps, versioned and shareable.
• Heavy -- BMAD runs a pipeline of role-played agents (analyst → PM → architect → QA → dev), producing brief → PRD → architecture "before a single line of code is written" (BMAD-METHOD).

Same move -- break down, pin intent, build -- at different weights. Match the ceremony to the stakes.

The honest caveat

• Intent, not truth. A spec is the source of intent; the code is what actually runs (RedMonk).
• No perfect one-sweep. Generation is non-deterministic -- the same spec yields different code across models, or even twice on one model, so it drifts from any frozen version (Birgitta Böckeler).
• Worth it when it lasts. The effort pays off for work with stakes and a lifespan; for a throwaway it is overhead. Vibe to find the idea, spec to build the thing you keep.

Last reviewed: 2026-06-25