Spec-Driven Development (SDD) for AI Agents & When to Skip It

Spec-driven development flips the AI coding workflow: you write a precise, versioned specification first, and the agent implements to it — with the spec, not the code, as the source of truth. It emerged in 2025 as the antidote to vibe coding. This guide separates SDD from TDD, maps the tools that disagree on what the loop even is, and gives you a blast-radius rule for when a spec is worth the token tax.

What SDD actually is

Spec-driven development (SDD) treats the specification as the source of truth and code as a downstream artifact generated to match it. GitHub, whose Spec Kit toolkit popularized the term, frames it bluntly: intent is the source of truth, and code serves specifications, not the reverse. You write the goals, architecture, constraints and acceptance criteria first; the agent turns that into an implementation; and when the two drift, you fix the spec and regenerate — not the other way around.

SDD emerged in 2025 as a direct response to a failure mode of AI coding: agents produce plausible code that drifts from intent, hallucinates APIs, and decays as the project scales. The named villain is vibe coding — Andrej Karpathy's early-2025 coinage for writing a short prompt, letting the agent generate, running it locally, checking whether it matches expectation, and iterating until it is good enough. Note the contrast only holds against that loose prompt-and-hope sense, not against all AI-assisted coding.

Why does this suit agents specifically? Agents are extraordinarily good at generating code and nearly incapable of maintaining long-term coherence without structured context. A spec removes the guessing at thousands of unstated requirements. It lets a human review the plan before a single line of code exists, and it hands the agent checkable acceptance criteria instead of vibes. If you are new to running these agents day to day, our guide to using Claude Code is a useful companion here.

SDD vs vibe coding vs TDD

The most common confusion is SDD versus test-driven development. They are not competitors — they operate at different altitudes and often coexist. TDD's primary artifact is a failing unit test (write test, write code, refactor) that answers a narrow question: is this implementation correct? SDD's primary artifact is a spec — architecture, non-functional requirements, constraints — that answers a broader one: is this the implementation we agreed to build? Crucially, most SDD workflows still produce TDD-style tests as an output of the spec.

The economics matter. Vibe coding is faster for the first twenty minutes and slower every hour after, because review and rework cost is paid at the end, when changes are most expensive. SDD front-loads that cost into a phase where changing your mind is cheap — you are editing markdown, not untangling generated code.

The Specify-to-Verify loop

The canonical SDD loop is Specify, Plan, Tasks, Implement — each phase producing a markdown artifact that feeds the next. Claude-Code-flavored descriptions often frame it as Specify, Plan, Implement, Validate. Either way, the point is that structure is a chain of reviewable documents, not a single monolithic prompt.

The last box is the one teams skip and regret. Specs with checkable success criteria — npm test passes, curl returns 200 — produce more reliable agent outcomes than interpretable criteria like well-structured code or good performance. An agent cannot verify a vibe. It can verify an exit code. That single discipline is most of the value.

The tools disagree on the loop

Here is the information-gain point most definitive guides skip: the loop is not standardized. Every tool recites Specify-Plan-Tasks-Implement, but the actual artifacts and file names differ enough that you cannot copy one team's setup into another tool. Map your own tool before you commit:

• GitHub Spec Kit (launched September 2, 2025) uses sequential slash commands: /constitution writes non-negotiable project principles into .specify/memory/constitution.md, then /specify, /plan, /tasks, /implement. Tasks are organized by user story, ordered by dependency, with parallelizable ones marked [P]. It bolts onto existing agents — Copilot, Claude Code, Gemini CLI and others.
• AWS Kiro is an agentic IDE built on SDD. It converts a prompt into requirements.md using EARS notation (WHEN [condition] THE SYSTEM SHALL [behavior]), then design.md for architecture, then a sequenced tasks.md checklist. Kiro previewed in 2025 and had a broader international launch in 2026.
• Claude Code offers a read-only Plan Mode: the agent analyzes the codebase and drafts a plan or spec but writes no code until you approve it. That makes it the tool for the planning phase specifically. Pair it with a standing CLAUDE.md or AGENTS.md that rides along in every session as persistent project context, plus task-specific specs for scope.

The pattern underneath all three: a standing instruction file for durable context, and a per-task spec for the thing you are building right now. If you push this further into reusable capability packs, our write-up on Claude Code Skills covers how to package specs and workflows so agents reuse them. And when you split planning from execution across models, the orchestrator-executor pattern is essentially SDD with the spec-writer and the implementer as different agents.

When to spec vs when to vibe

Most posts end with always write a spec. That is wrong, and the honest practitioners say so. SDD is considered overkill for throwaway prototypes, solo short-lived projects, and genuine exploratory coding — anywhere speed to market dominates and the code will not outlive the week. Writing a high-quality spec takes time, domain knowledge, and the discipline to think through edge cases before you know if the idea even works.

Instead of a blanket rule, triage by blast radius and reversibility. The heuristic that shows up across the honest sources: the moment another human touches the code, or it touches money or user data, write the spec first. Below that line, vibe coding is often the rational choice — the review-at-the-end cost never gets large enough to matter.

• Vibe it: a one-off script, a spike to test feasibility, a solo weekend project, a UI you are still exploring. Reach for a fast, cheap coder — see the best cheap LLMs for coding, or route to DeepSeek V4 Flash for high-volume throwaway work.
• Spec it: anything multi-person, anything that moves money, anything that touches user data, anything hard to reverse once shipped. Draft the spec in Claude Opus 4.8 plan mode, then hand the tasks to an implementer like Qwen3 Coder Next.

If you route by phase across many models, a router that swaps model per task keeps this clean — our Claude Code Router guide walks through wiring plan and implement steps to different backends.

The honest costs

SDD is not free, and pretending otherwise is how teams get burned. The core trade-off: SDD shifts investment heavily upfront in exchange for clarity, quality, maintainability, and far fewer regenerate-from-scratch cycles. That upfront phase is a genuine disadvantage where speed to market is the whole game.

Three named failure modes are worth internalizing before you adopt it:

• Specs go stale. A spec only has value if it stays accurate. The moment the code and the spec disagree and nobody reconciles them, the spec becomes lying documentation — worse than none, because people trust it.
• Waterfall in markdown. Critics dismiss SDD as reinvented waterfall. The critique lands whenever a spec is written once, frozen, and handed off. It misses when the spec stays a living document revised as you learn.
• The token tax. Every time reality forces an architectural pivot, you pay again to re-explain the change to the agent — re-feeding context, regenerating downstream artifacts. On a project that pivots often, this tax can erase the savings.

Reported benefits — several-times-higher first-pass success on non-trivial tasks, order-of-magnitude fewer regenerate cycles, tens of thousands of GitHub stars on Spec Kit — circulate widely, but they originate largely from vendor and early-adopter reports rather than verified primary telemetry. Treat them as directionally encouraging, not as measured fact. The reliable claim is the qualitative one: for work with real blast radius, a spec removes wrong turns that vibe coding pays for at the worst possible time.

FAQ