Spec-Driven Development: What It Is & How It Works

AI coding agents will build exactly what you ask for, which is the problem. Ask loosely, and you get vibe-coded output that works in the demo and falls apart at the first integration boundary. Spec-driven development (SDD) is the discipline that places a structured, agreed-upon spec ahead of code generation. As of mid-2026, it has moved from conference-hallway debate to shipping tools from GitHub, Amazon, and a wave of startups.

This guide covers what spec-driven development is, the spec-first to spec-as-source spectrum, how it compares to TDD and BDD, what belongs in a good spec, and where the approach still breaks down. It's written for engineers and engineering leaders evaluating AI-assisted development workflows.

What Is Spec-Driven Development?

Spec-driven development (SDD) is a methodology in which a structured specification, not the prompt and not the code, is written and agreed upon first, and becomes the shared source of truth against which AI coding agents generate. The spec captures intent: what to build, for whom, under which constraints, and how you'll verify the result.

The term is young and still settling. Thoughtworks defines it as workflows that "begin with a structured functional specification, then proceed through multiple steps to break it down into smaller pieces, solutions, and tasks". Birgitta Böckeler, the Thoughtworks Distinguished Engineer whose October 2025 analysis anchors most current thinking on the topic, notes the term is already "semantically diffused," with some people using "spec" as a synonym for a detailed prompt.

That conflation misses what makes SDD different. A prompt is disposable; a spec is an artifact. It gets reviewed like code, versioned like code, and in the more ambitious versions of this workflow, it outlives the code it produced.

Why Spec-Driven Development Matters Now

Every software project loses information at handoffs. Microsoft's engineers call this "translation loss" and locate it at four points: stakeholder needs to product requirements, requirements to architecture and design, design to implementation, and implementation to validation. Human teams absorb some of that loss through hallway conversations and code review. An AI agent absorbs none of it. Whatever context isn't in the prompt simply doesn't exist for the model.

The stakes are measurable. In the widely cited "Asleep at the Keyboard" study (Pearce et al., IEEE S&P 2022), researchers generated 1,689 programs with GitHub Copilot across 89 security-relevant scenarios and found roughly 40% of them vulnerable. That study measured 2021-era models, and generation quality has improved since then, but the structural problem it points to hasn't changed: unit tests catch function-level bugs, not contract violations or architectural drift across service boundaries. Augment Code's guide makes the same point when it argues that specifications have to operate at the system level precisely because unit tests can't.

This is why the timing matters. Code generation is no longer the bottleneck; alignment is. Teams shipping with agents are discovering that the expensive failures aren't syntax errors; they're systems quietly diverging from intent, one of the forces reshaping architecture patterns for AI-native systems more broadly.

The Spectrum of SDD: Spec-First, Spec-Anchored, and Spec-as-Source

Not all spec-driven development is the same practice. Böckeler's three-level framework has become the standard vocabulary here, and it's worth learning because it separates a modest workflow change from a radical one. A January 2026 arXiv preprint by Deepak Babu Piskala, "Spec-Driven Development: From Code to Contract", adopts the same three levels, a sign the framework is hardening into consensus.

Spec-First

A well-thought-out spec is written before the work starts, drives the AI-assisted development workflow for that task, and is then largely abandoned. This is the entry point, and by Böckeler's observation, it's where nearly everything in the market actually sits today: "All SDD approaches, and definitions I've found are spec-first, but not all strive to be spec-anchored or spec-as-source."

Spec-Anchored

The spec is kept after the task ships and continues to serve the evolution and maintenance of that feature. The spec becomes a living contract: when behavior changes, the spec changes first, and some teams wire spec checks into CI/CD so divergence gets caught mechanically rather than in review.

Spec-as-Source

The spec is the main source file over time. Humans edit only the spec; the code is a generated output that the human never touches. Tessl's framework was the most explicit attempt at this end of the spectrum, treating the specification itself as the maintained artifact while still in private beta as of September 2025, per Thoughtworks' Radar write-up. The company has since repositioned around agent skills, which tells you something about how hard this level is to commercialize. GitHub's Spec Kit methodology gestures in the same direction with its claim that "code is the last-mile approach".

Most teams should start with spec-first and earn their way up. The further right you move on the spectrum, the more the spec's accuracy matters, because there's progressively less human contact with the code to catch what the spec got wrong.

Spec-Driven Development vs. TDD, BDD, and Vibe Coding

SDD keeps getting framed as a replacement for older disciplines, which muddles what it actually changes. The primary artifact is different, and so is the scope.

TDD asks you to define expected outcomes as failing tests; BDD asks teams to define behavior through collaborative scenarios. SDD sits upstream of both: it governs what the AI generates in the first place, rather than validating output after the fact. The disciplines stack rather than compete. Spec Kit's own methodology bakes test-first into its implementation phase, requiring tests before implementation code gets written.

Vibe coding is the real foil. Heeki Park, a solutions architect who documented his spec-driven workflow with Claude Code, put it well: spec-driven development "can act as brakes on vibe coding, reinforcing good software engineering practices while taking advantage of productivity gains from generative AI." The productivity is real in both modes. The difference is whether anyone can say, three months later, what the system was supposed to do.

What Belongs in a Good Spec

A spec that's just a longer prompt buys you nothing. The versions that work share five elements (Augment Code's guide slices a similar set into six):

• Intended outcome. What changes for the user or the system when this ships, stated concretely enough to test.
• Explicit scope boundaries. What's in, and just as deliberately, what's out.
• Constraints and prior decisions. The tech stack, latency budgets, compliance requirements, and architecture decisions the implementation must respect.
• Task breakdown. Discrete, verifiable steps an agent (or a person) can execute and check off.
• Verification criteria. Acceptance criteria and edge cases: how you'll know the task is complete, not just plausible.

Here's the shape of a lightweight spec, compressed to its skeleton:

## Feature: Payment retry handling
Outcome: failed card payments retry automatically; no duplicate charges

In scope: retry policy, idempotency keys, customer notification

Out of scope: new payment providers, refund flows

Constraints: must use existing events service; p95 latency < 200ms

Acceptance criteria:
- Retries use exponential backoff (1s, 2s, 4s), max 3 attempts
- Duplicate webhook deliveries produce exactly one charge
- Edge cases: partial captures, expired cards mid-retry

Tooling can scaffold the structure. GitHub Spec Kit anchors every project in a "constitution" of immutable principles that govern how specifications become code, and its optional checklist command describes itself as "unit tests for English".

Notice what none of the tooling scaffolds for you: the constraints and prior decisions element. Scope and acceptance criteria come from the feature. Constraints come from the system, and in most organizations, the system's documented state lags its actual state badly.

A spec that says "must use existing events service" is only useful if the author knows that service exists, what it can handle, and who else depends on it. That's an architecture question, and answering it from a diagram that was accurate two quarters ago is how confident specs go wrong. It's the same class of problem that motivates reasoning over live architecture graphs instead of static docs.

Popular Spec-Driven Development Tools

The tooling landscape splits into code-level tools that enforce spec-to-code alignment and an architecture layer above them. As of mid-2026, the code-level options worth knowing:

GitHub Spec Kit. An open-source (MIT-licensed) toolkit built around the Specify CLI. It installs slash commands into your agent of choice, and GitHub says it works with 30+ AI coding agents, including GitHub Copilot, Claude Code, and Cursor. The core workflow runs /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, then /speckit.implement. (Earlier coverage refers to bare /specify and /plan commands; the current commands carry the speckit. prefix.)

Kiro. Amazon's agentic AI development tool spans an IDE, CLI, and web interface. Its spec workflow generates three files per feature: requirements.md with user stories and acceptance criteria in EARS notation ("WHEN [condition/event] THE SYSTEM SHALL [expected behavior]"), design.md for technical architecture, and tasks.md as the implementation plan.

Tessl. The historically notable spec-as-source attempt, discussed above, date-stamp anything you read about it, since the company's positioning has shifted.

Claude Code. Not an SDD product per se, and it ships with no branded spec mode. It's a supported agent for Spec Kit (commands install to .claude/commands/), and practitioner accounts like Park's show teams running full spec-driven workflows inside it with nothing more than disciplined Markdown.

All four operate at the code level: they make sure the code matches the spec. Catio operates one level up, at the architecture layer; it works to ensure the spec matches reality. Catio maintains a real-time model of your architecture, grounded in what's running rather than what's documented. Archie, its reasoning agent, answers architecture questions and evaluates trade-offs against your actual infrastructure, source code, and data flows before a spec is written. Decisions then carry through to execution-ready designs and specs, which address the requirements-to-architecture handoff in Microsoft's translation-loss chain, the one code-level tools inherit rather than fix.

To be clear about the boundary: Catio doesn't generate your application code or replace Spec Kit and Kiro. It feeds them specs that are based on an accurate picture of the system.

Does Spec-Driven Development Actually Work? (Limitations and When to Skip It)

SDD measurably improves AI output on complex, multi-step work, but the evidence is early, mostly vendor-reported, and the workflows are heavier than the demos suggest. Thoughtworks placed spec-driven development in the Assess ring of its November 2025 Technology Radar, worth exploring but not yet a default recommendation.

The documented failure modes are specific enough to plan around:

• Review overload. Böckeler found that spec-kit produced a pile of repetitive Markdown files that were "very verbose and tedious to review". You've traded reviewing code for reviewing prose, and prose review is easier to rubber-stamp.
• A false sense of control. Even with all the templates and checklists in place, she "frequently saw the agent ultimately not follow all the instructions" or go overboard following them. A spec is an instruction, not a guarantee.
• One workflow doesn't fit all task sizes. Fixing a typo doesn't need a constitution. Microsoft's own guidance concedes that not every change needs the full lifecycle and adoption should be right-sized; IBM's guide warns against over-engineering the spec itself, debating a JSON key name for weeks.
• The open question underneath it all. The Radar entry puts it bluntly: "We may be relearning a bitter lesson," it warns, "that handcrafting detailed rules for AI ultimately doesn't scale."

There's a quieter failure mode the tooling debate skips past. Every mechanism above polices the spec-to-code contract. None of them checks the spec-to-system contract: whether the spec was right about the architecture it's building into. A perfectly enforced spec written against a stale dependency map still ships the wrong thing, with excellent traceability.

Skip SDD for exploratory prototypes, throwaway scripts, and single-file changes. Reach for it when multiple services, teams, or agents have to converge on the same intent.

How to Get Started with Spec-Driven Development

You don't need a platform decision to start. You need one feature and a week of time.

1. Pick one feature with visible alignment pain. Something that bounced between review cycles because the implementation kept missing the intent. That history is your baseline.
2. Write a lightweight spec. Outcome, scope boundaries, constraints, verification criteria, using the skeleton above. Pull constraints from what's actually running, not from the wiki. If nobody can confidently list what depends on the service you're touching, that's worth knowing before generation starts, not after.
3. Generate against it. Use whichever agent your team already runs, with Spec Kit or hand-rolled spec files. Keep the acceptance criteria in front of the agent for the whole session.
4. Review the diff against the spec, then decide. Did the spec catch misalignment earlier than your normal flow? If yes, expand to a second feature and consider keeping specs after they ship (spec-anchored). If no, your spec was probably missing constraints, which is a context problem more than a process one.

Teams that already run structured AI workflows adapt fastest; our write-up of effective AI engineering workflows at Catio shows what that discipline looks like in practice.

Conclusion

Microsoft's practitioners compressed spec-driven development into four words: "Spec quality = output quality." True, and incomplete. Spec quality depends on context quality. Code-level SDD solves prompt drift, but a spec written without an accurate, current model of the system it's changing will drift at the architecture level no matter how disciplined the workflow around it is.

Well-run teams will treat those as two halves of one practice: rigorous specs downstream and an accurate architectural model upstream. If the upstream half is your gap, see how Catio grounds specs and designs in a real-time model of your architecture.

FAQ

What is the difference between BDD and spec-driven development? BDD defines behavior through collaborative Given/When/Then scenarios validated by test automation. SDD makes a structured natural-language spec the source of truth from which AI agents generate code. BDD validates behavior after it's built; SDD governs generation before and while it happens, and can embed BDD-style scenarios in its verification criteria.

Does spec-driven development actually work? Early evidence says yes for complex, multi-step work: specs give AI agents durable context and catch misalignment before code review. But results are mostly vendor-reported, Thoughtworks still classifies SDD as "Assess" in late 2025, and practitioners report verbose spec sprawl and agents ignoring instructions. Pilot one feature before standardizing.

What is the difference between spec-driven development and TDD? TDD's primary artifact is a failing test written before code, operating at the function level. SDD's artifact is a system-level specification covering outcomes, scope, constraints, and acceptance criteria. They compose: GitHub Spec Kit's methodology, for one, requires that tests be written before implementation within the spec-driven loop.

What is spec-driven development vs code? In conventional development, code is the source of truth, and documentation decays around it. At SDD's far end (spec-as-source), that inverts: humans maintain the spec, and code becomes generated output, "the last-mile approach" in GitHub's phrase. Most teams today operate spec-first, where the spec guides generation, but code remains the maintained artifact.

‍