Spec-Driven Development

Category: Core Concepts Last updated: June 28, 2026

What Is Spec-Driven Development?

Spec-Driven Development (SDD) is a structured approach to building software with AI coding agents in which you write an explicit specification first, implement code against it, then validate that the implementation matches. The specification serves as the source of truth, keeping design intent and the actual code synchronized and preventing deviation.

SDD emerged in AI-assisted development as a counterpoint to informal "vibe coding"—where developers iteratively nudge an AI toward a result that "feels right." Rather than discovering misalignment after the fact, SDD makes intent explicit before implementation begins. It follows a clear pattern: write specification → implement code → validate alignment, with the workflow emphasizing a living specification that evolves with your system so teams work with shared understanding of what's being built.

Why SDD Matters Now

In the era of AI-assisted development, the quality of your outputs depends directly on the quality of your inputs. AI coding agents are powerful pattern matchers and code generators, but they lack deep understanding of your specific goals, constraints, and domain requirements. Without deliberate structure, the result is intent-to-implementation deviation—gradual divergence between what you actually wanted and what got built.

This deviation is a property of the workflow, not the model. In a vibe-coding loop, each prompt and correction focuses on the current concern. To satisfy new feedback, the agent often revises or overrides earlier decisions, and constraints that were previously implied or loosely stated are weakened or forgotten. Intent deviation may shrink at first as obvious gaps are fixed, but over time corrections become fragile: changes in one area introduce regressions in another, and the developer ends up in a sustained negotiation loop, repeatedly restating intent to keep the output on track. As the vibe coding vs SDD comparison puts it, this is not a model failure—it is a workflow limitation where context is not managed effectively.

SDD addresses this by making intent explicit, verifiable, and durable. It is the strategic end of context engineering—the practice of deliberately structuring information so AI agents build what you actually want rather than what they infer from ambiguous prompts. When the specification is the reference point, deviations become visible before they compound into larger problems.

Core Principles

Several principles distinguish spec-driven development from ad-hoc, prompt-by-prompt coding.

Intent as the Single Source of Truth

The core principle is to maintain the specification as the single source of truth for what the system does. This creates alignment benefits that compound over time:

Specification Before Code

SDD begins with specification first—defining what you're building before writing implementation code. Reviewing that specification is the cheapest place to fix issues, because catching a misunderstanding in the spec costs far less than discovering it in shipped code.

A Validation and Alignment Loop

Automated validation ensures implementations match the specification. Tests verify that the system behaves as specified, catching misalignments early when they're cheapest to fix. Because the spec is explicit, you can validate at any time by comparing code behavior against specification requirements.

A Living Specification

As systems grow beyond their first feature, the methodology's true value emerges. The key insight is that evolution requires regression prevention, especially when autonomous coding agents optimize for speed. Rather than allowing incremental changes to introduce deviation, successful SDD workflows maintain a living specification that captures the system's current state, so the system grows coherently rather than fragmenting into disconnected implementations.

Keep Specs Small and Human-Reviewable

A specification only delivers its benefits if a human can actually review it. Large, single-shot requests tend to produce a "mountain of markdown" that developers auto-approve without meaningful review—a trap worth naming as "vibe specifying." The discipline is to start small with line-or-two feature descriptions, slice work meaningfully using frameworks like INVEST and MoSCoW, and remember that specs are for humans first: if you cannot reasonably review it, it's too large. SDD provides its advantages over undisciplined vibe coding only when specifications are properly scaled and reviewed.

The SDD Workflow

At its heart, spec-driven development follows three phases: define the specification → implement against it → validate through checks. Teams first define the system specification as the shared understanding between stakeholders and AI coding agents; development then proceeds with clarity against that specification; and automated validation confirms the implementation matches. For a deeper treatment, see the spec-driven development workflows guide.

Most tools expand these three phases into roughly four, separating what from how. Individual tools may have a few more or fewer steps, but these aspects are usually covered:

  1. What (Specify / Propose / Requirements): Feature requirements and acceptance criteria, user needs and business goals, scope, boundaries, and non-goals.
  2. How (Design / Plan): Architecture and technical approach, technology and pattern choices, data models, APIs, and interfaces, plus risks and dependencies.
  3. Task (Granular Steps with Checks): Small, verifiable work items with clear validation criteria, explicit dependencies and ordering, and a testing strategy. Tasks may be delegated to sub-agents, reducing context burden in the primary thread while keeping intent anchored.
  4. Build (Implementation): Tasks executed sequentially or in parallel, validated against acceptance criteria, with automated tests run and the implementation reviewed against the specs.

Breaking work into explicit phases with review gates makes intent articulation deliberate and verifiable, significantly reducing downstream deviation. The output is working code that matches documented intent.

SDD vs Vibe Coding vs Plan Mode

Context engineering exists on a spectrum from tactical to strategic. Vibe coding, plan mode, and spec-driven development sit at different points along it.

Vibe coding is an informal, conversational approach where developers iteratively guide AI agents through natural language prompts, refining outputs until the implementation "feels right." It works well for quick prototypes and exploration but manages deviation reactively—you course-correct only once you notice divergence.

Plan mode, built into AI coding assistants such as Claude Code and Cursor, is a tactical step up: the agent proposes an implementation plan from a conversational prompt, you refine it, and implementation proceeds. It has low ceremony and fast iteration, but its context is ephemeral—plans live only in conversation history, not as persistent artifacts, so there is no authoritative reference when implementation deviates. See plan mode vs SDD for the full comparison.

Spec-driven development is the strategic end of the spectrum: you create structured, persistent specifications that serve as the source of truth and guide both AI and human developers over the long term. The trade-off is captured concisely in the vibe coding vs SDD analysis: vibe coding optimizes for speed, while spec-driven development optimizes for intent alignment. Vibe coding accepts deviation as a cost of speed; SDD reduces deviation by introducing structure, review gates, and explicit intent articulation. The guiding rule: if intent matters beyond the next prompt, structure wins.

Tools Landscape

Several tools support the spec-driven workflow with different emphases. Choosing among them depends on your team's workflow preferences and integration needs—the tool selection guide walks through the criteria in detail.

Each tool provides mechanisms for the core define → implement → validate loop while offering unique features for different team needs.

Customize the Tool to Your Process

Just as important as picking a tool is shaping it to your process rather than forcing your process to fit the tool. OpenSpec, for example, ships with a default spec-driven schema that produces proposal, specs, design, and tasks in sequence—but not every project fits that mold. Custom schemas let you define the artifacts themselves: a minimalist schema strips the workflow down to just specs and tasks for well-scoped, low-risk changes, while an event-driven schema adds event storming and modeling steps before the usual spec-design-task flow for systems built around asynchronous messaging. The guiding idea is that custom schemas let the tool fit your process rather than the other way around.

Spec-Driven Development for Brownfield Projects

In the context of SDD, a brownfield project is one that was not built from specs—the only artifact available is the code itself. It is tempting to bootstrap SDD by reverse-engineering a specification for the whole codebase, for instance by packing the code with a tool like Repomix and asking an LLM to generate the overall spec. In practice, AI-generated specs are often inaccurate: the model doesn't fully capture the original developer's intent or the subtle nuances embedded in the code, producing a spec that looks plausible on the surface but diverges from reality and can't be trusted as a foundation for future development.

There is also the problem of alignment loss. A reverse-engineered spec is a derived artifact, and when new features are developed against a misaligned spec, the risk of regressions and unintended side effects rises sharply, because the spec no longer reflects the real ground truth of the system.

A more reliable path is to author specs incrementally. Rather than attempting to capture the whole codebase at once, you write a spec for just the area you are about to change. This is far more economical: the scope is bounded, the context is fresh, and the resulting spec accurately reflects intent. Over time the practice compounds—each change leaves behind a spec that covers its slice of the system, and as spec density grows in frequently touched areas, those sections start to behave like greenfield zones. The coverage builds naturally where it matters most, without a big upfront investment in reverse-engineered specs that may not hold up. See Spec-Driven Development with Brownfield Projects for a worked example.

Common Misconceptions

"Isn't SDD just heavy documentation that conflicts with Agile?"

Spec-Driven Development is sometimes criticized as an anti-pattern because it appears to conflict with "Working software over comprehensive documentation" from the Agile Manifesto. This criticism often stems from viewing specs as artifacts rather than as a mechanism for intent negotiation. Behaviour-Driven Development was never about Gherkin syntax for its own sake—it was about enabling collaboration between business and technology through structured conversation, which aligns with "Collaboration over contract negotiation." Similarly, SDD facilitates structured conversation between humans and coding agents. Specs and plans are not the goal; they are scaffolding that helps clarify and stabilize intent.

"Doesn't writing specs just slow you down?"

SDD does frontload clarity and carries a higher upfront cost than starting to code immediately. But that upfront work makes intent explicit before implementation begins, which reduces costly rework and maintains alignment over time. It can feel like overhead for tiny features—which is exactly why lighter approaches exist for those cases—but for complex or long-lived work, the structure pays for itself by preventing deviation.

"SDD is only for greenfield projects."

Spec-driven development applies to existing systems too. As the brownfield section above describes, the practical path is not to reverse-engineer one large specification but to author specs incrementally—one upcoming change at a time—so coverage builds naturally where it matters most.

Resources