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:

1. Specify — what to build and why (requirements, user stories, scenarios).
2. Plan / Design — the technical approach, architecture, trade-offs.
3. Tasks — a checklist of small, independently verifiable units of work.
4. 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

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