What is spec-driven development (SDD)?

Spec-driven development (SDD) is a way of building software where you write structured specifications first—requirements, constraints, acceptance criteria, and architecture decisions—and those specs drive plans, tasks, and implementation. With AI coding agents, SDD replaces vague "build me X" prompts with versioned artifacts in the repo that humans and agents can execute against repeatedly.

The useful contrast is not SDD vs AI, but SDD vs vibe coding: SDD keeps the speed of assistant-driven development while adding traceability, review checkpoints, and a source of truth that survives beyond a single chat session.

Core ideas

• Spec as source of truth — Architecture, constraints, and acceptance criteria live in versioned files (not ephemeral chat history).
• Executable workflow — Specs decompose into plans and tasks that agents or humans can run in a repeatable loop.
• Traceability — When requirements change, you update the spec and regenerate downstream work instead of re-explaining context in chat.
• Human checkpoints — SDD adds structure; it does not remove code review, tests, or ownership of merges.

A typical SDD loop looks like this:

Intent → Spec → Plan → Tasks → Implementation → Verify

WavePillars treats SDD as the disciplined layer on top of AI-assisted development: you still iterate fast, but intent stays explicit and auditable.

SDD vs vibe coding

Vibe coding names a real shift—natural language and fast iteration as the default path to code. SDD addresses what goes wrong when that loop has no persistent structure: context rot, inconsistent architecture, and code nobody can explain at 2 a.m.

Neither approach replaces the other entirely. Use vibe coding for exploration; use SDD when multiple people, agents, or releases depend on the same intent staying stable.

Well-known SDD frameworks

Several open-source and productized frameworks have emerged to standardize how specs, plans, and tasks flow into agent-driven implementation. Here is a practical survey.

GitHub Spec Kit

GitHub Spec Kit is the most widely adopted open-source SDD toolkit. It flips the traditional model: instead of specs being scaffolding discarded after coding starts, specifications become executable—directly generating plans, task lists, and implementation guidance for AI agents.

Typical workflow

1. Run specify init to scaffold a project (or specify init --here in an existing repo).
2. Use /speckit.specify to capture what you are building and why.
3. Run /speckit.plan and /speckit.tasks to break the spec into actionable work.
4. Implement with your agent of choice; the constitution file keeps non-negotiable rules visible.

Install

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init my-project --ai claude

When to pick it: Greenfield products, teams that want a standard repo layout, and projects using Cursor, Copilot, Claude Code, or Gemini CLI where slash-command workflows fit naturally.

OpenSpec

OpenSpec (Fission-AI) centers on change proposals as durable artifacts. Instead of jumping straight to code, you propose a spec change, apply it through a guided workflow, and archive completed work—keeping a clear history of what changed and why.

Typical workflow

1. /opsx:propose — draft a structured change proposal.
2. /opsx:apply — execute the proposal through plans and implementation.
3. /opsx:archive — close out the change with traceability intact.

Install

npm install -g @fission-ai/openspec@latest

When to pick it: Teams that want proposal-driven change management in the repo, especially when multiple agents or contributors touch the same codebase and you need explicit before/after spec diffs.

BMAD Method

The BMAD Method (Breakthrough Method for Agile AI Driven Development) simulates a full agile team with specialized AI agents—Business Analyst, Product Manager, Architect, Developer, UX Designer, QA, and others. Workflows adapt to project scale, from a bug fix to an enterprise system.

Typical workflow

1. Brainstorm and analyze with BA/PM agents.
2. Produce architecture and story breakdown with Architect/Scrum Master agents.
3. Implement and review with Dev/QA agents; Party Mode enables multi-agent collaboration on complex decisions.

When to pick it: Larger or multi-role delivery where you want structured agile ceremonies encoded in agent workflows—not just a single spec file, but a full lifecycle from discovery to deployment.

Kiro (AWS)

Kiro is a spec-driven IDE from AWS. Requirements, design documents, and task lists live inside the editor, with agents that read those artifacts before generating code. It supports architecture specifications and domain-driven decomposition for microservices-style systems.

Typical workflow

1. Write requirements and acceptance criteria in Kiro's spec views.
2. Generate design and task breakdown from the spec.
3. Implement with in-IDE agents grounded in the same documents.

When to pick it: Teams already on AWS who want an IDE-native SDD experience rather than CLI scaffolding—especially when architecture specs and DDD-style service boundaries matter.

Lightweight SDD without a framework

You do not always need a dedicated toolkit. Common lightweight patterns:

• Cursor Plan mode — Draft a plan before agent mode applies large diffs.
• AGENTS.md and .cursor/rules — Persistent instructions agents read every session.
• OpenAPI, PRD, or ADR docs — Treat existing documents as specs; agents implement against them with explicit acceptance criteria.

Use these when a full framework would be overkill but you still want repo-local intent instead of chat-only context.

Choosing a framework

• Greenfield product → GitHub Spec Kit or OpenSpec for repo scaffolding and agent commands.
• Large / multi-role delivery → BMAD Method for full agile agent workflows.
• IDE-native, AWS shop → Kiro for in-editor specs and architecture decomposition.
• Existing codebase, incremental adoption → specify init --here with Spec Kit.

Start with the smallest structure that fixes your pain. You can always graduate from Plan mode + AGENTS.md to Spec Kit or OpenSpec when the team outgrows informal specs.

When SDD helps—and when to skip

Good fits

• New features with clear requirements and acceptance criteria
• AI-heavy teams where chat context does not scale across sessions
• Shared repos where multiple people or agents need the same source of truth
• Regulated or audit-friendly work where decisions must be documented
• Refactors where behavior must stay explicit and testable

Skip or stay lightweight

• One-off scripts and throwaway spikes
• Exploratory UI where the design evolves faster than a spec can keep up
• Trivial changes already covered by tests and a one-line PR description

SDD is a discipline, not a tax. If writing the spec takes longer than doing the work, the scope is probably too small for a full framework.

Practices that work

1. Keep specs small and scoped—one feature or module, not the entire product in a single file.
2. Version specs in git alongside code; treat spec changes like API changes.
3. Derive tests from acceptance criteria in the spec; generated code must prove the spec, not replace it.
4. Use human review at plan and task boundaries before large agent diffs land on main.
5. Combine SDD with MCP tools when specs need live system context—schemas, APIs, or staging data. See What is the MCP Protocol? for how assistants reach real systems safely.
6. Publish team conventions (rules, constitution, or bootstrap files) so every agent session starts from the same baseline.
7. Reconcile specs after shipping—if implementation diverged for good reasons, update the spec so the next agent does not undo the fix.

Team adoption

Rolling SDD out across a team mirrors any process change:

• Agree when a spec is required (all features vs epics above a size threshold).
• Pick one framework (or lightweight pattern) and standardize repo layout before letting every developer choose their own.
• Require spec review in PRs for AI-heavy changes—the same bar as code review.
• Track revert rate and incident count on spec-driven vs ad-hoc agent PRs; tune workflow when quality slips.

Leads should model good specs in early PRs: clear acceptance criteria, explicit non-goals, and constraints the model cannot infer from the codebase alone.

Summary

Spec-driven development makes structured specifications the source of truth for AI-assisted and human development. Specs drive plans and tasks; agents execute against repo-local artifacts instead of fading chat context. Frameworks like GitHub Spec Kit, OpenSpec, BMAD, and Kiro encode different trade-offs—from CLI scaffolding to multi-agent agile to IDE-native specs.

Use SDD when traceability, team alignment, and repeatable agent workflows matter. Keep vibe coding for exploration; use SDD when something ships and someone else will maintain it.

Related reading

• What is vibe coding? — intent-first AI development and when to add guardrails
• What is the MCP Protocol? — tools, resources, and prompts for grounded agent work