Spec-Driven Development with AI Coding Agents: A Practical Guide for Claude Code, Codex & Cursor

Spec-Driven Development flips AI coding on its head: the specification becomes the source of truth and code becomes a generated artifact. Here's what SDD means, the tools that power it (GitHub Spec Kit, Kiro, Tessl, cc-sdd), how it works with Claude Code, Codex, and Cursor, plus the benefits, criticisms, and a practical workflow.

Illustration of a structured specification document flowing into generated code, guided by an AI agent — representing Spec-Driven Development.

AI coding agents can now generate working software from a sentence. That speed is intoxicating, and it has a name when it goes wrong: vibe coding. Spec-Driven Development (SDD) is the discipline that puts structure back into the loop. Instead of prompting an agent and hoping for the best, you write a specification first and let the agent implement against it. The spec, not the code, becomes the thing you maintain.

info

TL;DR

SDD inverts the traditional workflow: the specification (the what and why) is the source of truth, and code becomes a generated or verified secondary artifact. Tools like GitHub Spec Kit, Amazon Kiro, Tessl, and cc-sdd bring this workflow to Claude Code, OpenAI Codex, and Cursor. Benefits are real but mostly qualitative; the strongest criticisms are practical (spec drift, overhead) rather than conceptual.

The Shift in Software Development

For decades, software development was constrained by the cost of writing code. Teams spent most of their time translating requirements into implementation, so development processes naturally evolved around managing code complexity.

AI coding agents are changing that equation. Tools like Claude Code, Codex, and Cursor can now generate large amounts of working code from natural language instructions. As code generation becomes cheaper and faster, a different bottleneck emerges: defining what should be built in the first place.

The challenge is no longer getting code written. The challenge is expressing intent clearly enough that both humans and AI systems understand the same thing. This shift helps explain the rise of Spec-Driven Development: when generating code becomes easy, defining the right thing to build becomes the harder problem.

What Is Spec-Driven Development?

Spec-Driven Development is a paradigm that decouples the specification (what you want and why) from the implementation (how it gets built). It inverts the traditional code-first workflow: the spec becomes the authoritative source of truth, and code becomes a generated or verified secondary artifact. As GitHub puts it, we are moving from "code is the source of truth" to "intent is the source of truth."

Crucially, the spec is not a throwaway document. It is treated as a living, executable artifact that evolves with the project, and as a contract between humans and AI agents. That contract makes technical decisions explicit, reviewable, and evolvable. One Microsoft engineer described it as "version control for your thinking."

SDD vs. "Vibe Coding"

SDD is explicitly positioned against vibe coding, the informal, prompt-and-pray style of iterating with an AI. High-level prompts are fast, but they tend to produce disposable code and mounting technical debt. SDD is framed as the professional, disciplined response to unsupervised AI generation: you spend a little structure up front to get durable, reviewable output.

warning

A nuance worth keeping honest

It is accurate to say SDD is positioned in contrast to vibe coding. It is an overstatement to say tools like Spec Kit are designed to 'replace' vibe coding entirely. SDD is about adding rigor where it pays off, not banning fast iteration everywhere.

The Tooling Landscape

Several named tools implement SDD, and they embody distinct levels of rigor, from human-gated phases to full code regeneration from the spec.

GitHub Spec Kit

The most prominent entry. Spec Kit is an open-source, MIT-licensed Python CLI (the Specify CLI) that orchestrates AI coding agents through a structured four-phase workflow: Specify, Plan, Tasks, Implement. It is cross-agent by default, with built-in templates that work across 30+ AI coding agents without per-agent edits.

Amazon Kiro

Kiro enforces a sequential, stage-gated flow that produces three artifacts before any code is generated: requirements.md, design.md, and tasks.md. Each stage must be reviewed and accepted before moving on, which makes Kiro the most explicitly gated of the popular tools.

Tessl

Tessl represents the most aggressive model: spec-as-source. The specification is the maintained artifact, and code is regenerated from it, often marked "GENERATED FROM SPEC - DO NOT EDIT." You stop editing code by hand and edit the spec instead.

cc-sdd

A community Node.js CLI that installs SDD workflows as 17 reusable skills into your agent. It supports 8 agents, with Claude Code and Codex rated Stable, and Cursor, Copilot, Windsurf, OpenCode, Gemini CLI, and Antigravity in Beta. Its flow runs Discovery, Requirements (in EARS format with acceptance criteria), Design (architecture plus Mermaid diagrams), Tasks, and Implementation with per-task test-driven development.

install-cc-sdd.sh

# Install SDD skills into your agent of choice
npx cc-sdd@latest --claude-skills    # Claude Code (Stable)
npx cc-sdd@latest --codex-skills     # OpenAI Codex (Stable)
npx cc-sdd@latest --cursor-skills    # Cursor (Beta)
npx cc-sdd@latest --gemini-skills    # Gemini CLI (Beta)

spec-kitty

An open-source Python CLI that tackles a specific pain point: AI sessions losing the requirements mid-task. It stores specs, plans, tasks, reviews, and merge state in the repository (under kitty-specs/) rather than in agent-only prompt text, following a lifecycle of spec, plan, tasks, next, review, accept, merge.

How It Works with Claude Code, Codex & Cursor

The big win of the leading tools is that they are agent-agnostic. With Spec Kit, you pick your agent at init time and the same templates drive Claude Code, OpenAI Codex CLI, Cursor (via cursor-agent), GitHub Copilot, Gemini CLI, Kiro CLI, and more. The workflow you run inside each agent is identical, expressed as namespaced slash commands.

The three core authoring commands do most of the work:

/specify — capture requirements: the what and why, deliberately excluding technology choices.
/plan — define the technical approach: frameworks, libraries, databases, and constraints.
/tasks — break the plan into small, reviewable, testable chunks the agent can implement one at a time.

Surrounding steps like clarify, analyze, and checklist are optional. In current Spec Kit, these commands are namespaced (for example /speckit.specify); older guides show the un-namespaced names. Always check the live repo for the exact command names, since they have changed over time.

A Practical Workflow & Best Practices

Start with intent, not implementation. Write the spec describing user journeys and success metrics before naming a single library.
Add a constitution. Capture durable project principles (coding standards, non-negotiables) so every generated task inherits them.
Clarify before you plan. Resolve ambiguities explicitly; an unclear spec produces confidently wrong code.
Keep tasks small and testable. Review each task before the agent moves on, so a wrong turn is caught early and cheaply.
Commit the spec to the repo. Treat specs, plans, and tasks as version-controlled artifacts, not chat history. This is the single best defense against spec drift.

Benefits

Reduced ambiguity — the agent implements against an explicit contract instead of guessing.
Durable, reviewable artifacts that survive across AI sessions and onboard new contributors.
Human review gates at each phase, keeping a person in control of consequential decisions.

Criticisms & Limitations

Notably, the documented criticisms of SDD are mostly practical rather than conceptual. Even skeptics tend to accept the definition and intent; they question whether it pays off in practice:

Spec drift — specs fall out of sync with code over a project's lifetime. This is the most common complaint.
Time overhead — the up-front discipline costs effort that does not always pay back.
Poor fit for exploration — for prototyping and throwaway work, heavyweight specs can get in the way.

The Evidence: What's Proven and What Isn't

warning

Mind the evidence gap

Most sources for SDD are vendor documentation (GitHub, Microsoft, tool authors). They are authoritative on features but advocacy-toned on benefits. A widely repeated claim that human-refined specs cut LLM code errors by up to 50% did not hold up under scrutiny. Treat the benefits as qualitative and intended, not as empirically proven gains in defect rate or velocity.

The honest summary: the definition and tooling are well established, but rigorous, independent evidence that SDD beats traditional workflows or vibe coding on quality and speed is still thin. Adopt it because the structure and review gates are valuable, not because a benchmark promises a specific percentage.

Developers May Become Architects Before Programmers

Spec-Driven Development reflects a broader shift in software engineering. As AI agents become better at generating code, the scarce resource is no longer implementation effort but clarity of intent.

In practice, this means developers may spend less time translating requirements into code and more time defining requirements, designing systems, and reviewing AI-generated output. The competitive advantage increasingly comes from understanding the problem rather than typing the solution.

SDD does not replace programming; it elevates the importance of architecture, product thinking, and specification writing in the development process.

Should You Adopt SDD?

If you are shipping production software with AI agents, SDD is worth adopting: the explicit contract, human review gates, and repo-stored artifacts are exactly the guardrails that fast AI generation lacks. Start light with Spec Kit or cc-sdd on Claude Code, Codex, or Cursor, keep your specs in version control, and reserve full spec-as-source models like Tessl for greenfield work where regeneration is cheap. For quick prototypes and exploration, it is fine to keep vibe coding — just know which mode you are in.

Join the MySpec Open Beta and experience Vibe Specify’ing today.