What Is Spec-Driven Development (SDD)?

What is it

Spec-Driven Development (SDD) is a discipline for working with AI agents where every phase of the development cycle produces a formal, reviewable artifact before moving to the next: a proposal, a specification, a technical design, a task list. It isn't a tool or a specific framework — it's an organizing principle that any harness can implement its own way.

The usual alternative — telling an agent "implement X" in a single prompt — works for small changes, but breaks down fast on real projects: the agent makes scope, architecture, and edge-case decisions with nobody reviewing them, and those decisions end up buried in a conversation nobody reopens.

SDD splits the cycle into explicit phases — typically proposal, spec, design, tasks, implementation, verification, and archive — each with its own artifact to review before continuing.

Mental model

Think of the difference between telling a contractor "build a house" versus "build a house, but show me the blueprints first, then the itemized budget, and only then start building." In the second case, every handoff is a checkpoint where you can say "not this," before the mistake costs an entire wall.

These phases are generic — any SDD implementation names them its own way. The concrete commands shown below (/sdd-new, /sdd-spec...) belong to gentle-ai, one suite among several that apply the same principle across the industry — GitHub Spec Kit, for example, uses its own slash-command syntax.

Every arrow is a point where a human can approve, request changes, or stop — before the agent moves to the next phase on a wrong foundation.

How it's used

In practice, SDD gets implemented through skills or commands that turn each phase into a real artifact on disk, not just chat text:

/sdd-new change-name      # proposal: what and why
/sdd-spec                  # spec: requirements, acceptance criteria
/sdd-design                # technical design: how, with what trade-offs
/sdd-tasks                  # ordered, scoped task list
/sdd-apply                  # implementation, task by task
/sdd-verify                 # validation against the original spec

Each phase reads the previous phase's artifact — design doesn't get invented in a vacuum, it answers the spec; tasks don't get invented in a vacuum, they answer the design. That's what stops the agent from improvising architecture mid-implementation.

When to use it / when not to

Use it when:

• The change touches several files or components and design decisions matter.
• You'll need traceability — being able to answer "why was this built this way" months later.
• You work on a team and the spec or design need review before implementation starts.
• The feature is large enough that "one long conversation" would lose the thread.

It's overkill when:

• The change is a one-line fix — the overhead of five phases doesn't pay for itself.
• You're exploring or prototyping and don't know yet what you want to build.
• The task is purely mechanical with no real design decision worth documenting.