Spec-Driven Development

Wed, 17 Jun 2026 10:00:00 +0800

Spec-Driven Development

Spec-Driven Development (SDD) is a methodology for building software with AI coding agents where the specification, not the code, is the primary artifact. Instead of prompting an agent ad-hoc and hoping the output is correct, you first write down what you want — requirements, scenarios, constraints — and let the spec drive the plan, the tasks, and finally the implementation.

The core idea: AI agents are powerful but unpredictable. A natural-language prompt is lossy and easy to misread, and the larger the change, the more drift accumulates. A spec turns intent into a reviewable, version-controlled, executable contract. Humans and agents align before code is written, and the spec stays as living documentation afterwards.

Why SDD

The classic “vibe coding” loop (prompt → diff → fix → prompt again) breaks down as soon as the task is non-trivial:

Ambiguity. The agent fills gaps with assumptions you never see.
Drift. Multi-step changes lose the original intent halfway through.
No source of truth. Once the chat is gone, why the code looks this way is gone too.
Hard to review. Reviewing a 600-line diff is much harder than reviewing a one-page spec that produced it.

SDD addresses these by inserting an explicit, cheap-to-review specification step in front of code generation. The phases are roughly:

Specify — what to build and why (requirements, user stories, scenarios).
Plan / Design — the technical approach, architecture, trade-offs.
Tasks — a checklist of small, independently verifiable units of work.
Implement — the agent executes tasks against the spec.

The tools below differ mainly in how heavy this process is and whether the spec is a living document or a throwaway scaffold.

GitHub Spec Kit

https://github.com/github/spec-kit

GitHub’s official, opinionated take on SDD. It ships a CLI (specify, installed via uv) that bootstraps a project and wires a full set of slash commands into your agent of choice.

The workflow is a sequence of gated phases:

/speckit.constitution — establish project principles and governance.
/speckit.specify — define requirements and user stories.
/speckit.plan — create the technical implementation strategy.
/speckit.tasks — generate an actionable task breakdown.
/speckit.implement — execute the tasks systematically.

Plus optional helpers: /speckit.clarify (resolve ambiguities before planning), /speckit.analyze (cross-artifact consistency checks), and /speckit.checklist (custom quality gates).

uv tool install specify-cli
specify init my-project
specify integration list # 30+ supported agents

Pros

Backed by GitHub; mature, well-documented, actively developed.
Genuinely thorough — the constitution + clarify + analyze steps catch ambiguity and inconsistency early.
Technology-agnostic; supports 30+ agents (Copilot, Claude Code, Gemini CLI, Cursor, Codex CLI, …).
TDD-compatible task generation and parallel-task markers.

Cons

Heavyweight. The full phase sequence is overkill for small changes.
Requires Python 3.11+, uv, and Git just to bootstrap.
Strongly greenfield-flavored; the constitution/specify flow assumes you are starting something new rather than evolving an existing codebase.

Best for: new projects, larger features, and teams that want a rigorous, repeatable process with explicit governance and review gates.

OpenSpec

https://github.com/Fission-AI/OpenSpec

A lightweight, change-oriented alternative. Rather than treating the spec as a one-shot scaffold, OpenSpec maintains living specs and models work as a series of change proposals layered on top of them.

The repository keeps two key areas:

specs/ — the current, agreed-upon truth (what the system does today).
changes/ — proposed deltas (a proposal, spec changes, design notes, and a task checklist) for work in flight.

The loop is intentionally small:

/opsx:propose — open a new change proposal.
/opsx:apply — implement the proposed tasks.
/opsx:archive — fold a completed change back into the specs and archive it.

npx openspec init # also: openspec update to refresh agent instructions

Pros

Lightweight and fluid — iterates without rigid phase gates.
Equally at home in brownfield codebases; the spec/change split is built exactly for evolving existing systems.
Specs are durable living documentation, not throwaway scaffolding.
Node-based, minimal setup; integrates with 25+ tools.
MIT licensed.

Cons

Younger and smaller community than Spec Kit.
Fewer built-in quality gates — the discipline of clarify/analyze is on you.
The change/archive model takes a little practice to internalize.

Best for: ongoing work on existing codebases, incremental features, and developers who want alignment-before-code without ceremony.

Other notable tools

Two more worth knowing about, since they take meaningfully different shapes:

Amazon Kiro

https://kiro.dev/

An agentic IDE (rather than a CLI add-on) with SDD as a first-class feature. From a prompt it generates three artifacts — requirements.md (EARS-style acceptance criteria), design.md, and tasks.md — and keeps them in sync as you build. Pros: integrated end-to-end experience, structured requirements, strong onboarding. Cons: it’s a whole IDE to adopt and is more of a walled garden than the editor-agnostic CLIs above. Best for: developers willing to switch IDEs for a tightly integrated spec-to-code workflow.

BMAD-METHOD

https://github.com/bmad-code-org/BMAD-METHOD

“Breakthrough Method of Agile AI-Driven Development.” Less a spec format and more an agentic team: specialized agents (Analyst, PM, Architect, Scrum Master, Dev) collaborate to produce a PRD and architecture, then shard them into hyper-detailed story files that carry full context into implementation. Pros: rich, role-based planning; great for complex, multi-feature products. Cons: the most ceremony of the bunch; a real learning curve. Best for: ambitious greenfield products where up-front planning genuinely pays off.

How to choose

Tool	Weight	Greenfield	Brownfield	Setup	Living specs
Spec Kit	Heavy	Excellent	OK	Python + uv	Per-feature
OpenSpec	Light	Good	Excellent	Node	Yes (specs/)
Kiro	Medium	Excellent	Good	Dedicated IDE	Yes
BMAD-METHOD	Heavy	Excellent	OK	Node/agents	PRD + stories

A practical rule of thumb:

Starting a new project and want rigor → Spec Kit.
Evolving an existing codebase and want speed → OpenSpec.
Want an all-in-one IDE experience → Kiro.
Building an ambitious product with heavy planning needs → BMAD-METHOD.

All four are MIT/open and agent-agnostic enough to try in an afternoon. The common thread — and the real takeaway — is this: write the spec first, review the spec (not the diff), and let intent, not vibes, drive the agent.

Resources

https://github.com/github/spec-kit

https://github.com/Fission-AI/OpenSpec

https://kiro.dev/

https://github.com/bmad-code-org/BMAD-METHOD

Spec-Driven Development on Morgoth

Spec-Driven Development

Spec-Driven Development

Why SDD

GitHub Spec Kit

OpenSpec

Other notable tools

Amazon Kiro

BMAD-METHOD

How to choose

Resources