Spec-Driven Coding: The Complete Guide to AI Development 10x

AI coding agents are incredibly capable — and remarkably easy to misuse. The fastest way to turn a 10x tool into a 1x liability is to hand it a vague prompt and let it "figure it out." Agents fill in ambiguity confidently. They invent APIs that don't exist. They refactor files you never mentioned. Then you spend the evening reviewing a diff that looks nothing like what you asked for.

Spec-driven coding (SDD) is the answer the industry converged on in 2025–2026. Instead of prompting an agent and hoping, you write the specification first: what we're building, why, and the acceptance criteria. The agent implements against that spec — and the spec, not the prompt, becomes the source of truth.

This is the pillar article of our spec-driven coding cluster. New to the ecosystem? Our guides to GitHub Spec Kit, OpenSpec, BMad, and Superpowers each cover one major tool in depth, and the Spec Kit vs OpenSpec vs BMad comparison helps you choose.

Why "just prompt it" stops scaling

Vibe coding is fun in a fresh repository. The problems start the moment your project has real constraints:

| Problem | Why it happens | |---|---| | Agents invent APIs | No contract exists, so the model fills the gap with its best guess | | Work doesn't match intent | The user's intent was never written down in a form the agent could follow | | No review baseline | Without requirements, a reviewer can't tell "wrong" from "different" | | Context drift across sessions | Every new session re-learns the project from scratch | | Parallel agents conflict | Two agents editing one codebase without a shared plan |

Spec-driven coding attacks every row of that table with one move: make the requirements an explicit, versioned artifact before code exists. When the spec says "the endpoint accepts GET /orders/{id} and returns a 404 for unknown IDs," the agent isn't guessing — it's reading.

The core workflow: constitution → spec → plan → tasks → implement

The spec-driven ecosystem has converged on a five-stage pipeline. Every major tool implements some version of it:

1. Constitution   — project-wide principles the agent must obey
2. Spec           — what we're building and why (requirements, acceptance criteria)
3. Plan           — how we'll build it (architecture, data model, contracts)
4. Tasks          — ordered, granular work items with acceptance criteria
5. Implement      — the agent executes tasks; code serves the spec

1. Constitution

A short document of non-negotiable project rules: testing expectations, forbidden patterns, naming conventions, security requirements. In GitHub Spec Kit this is constitution.md, generated by /speckit.constitution and versioned with semantic versioning — a MINOR bump for a new principle, a MAJOR bump for a removed one. Every plan is checked against it before implementation starts.

2. Spec

The heart of the method. The spec answers "what and why" — never "how." A good spec contains:

Feature description and user problem statement
Functional requirements, numbered (FR-001, FR-002…)
Non-functional requirements (performance, security, accessibility)
Scenarios and success criteria
Explicit non-goals

In Spec Kit, ambiguity is surfaced as [NEEDS CLARIFICATION] markers — the tool literally refuses to guess. In OpenSpec, specs live in openspec/specs/ and every change is a delta spec (ADDED / MODIFIED / REMOVED), so reviewers see exactly how requirements changed before a single line of code is written.

3. Plan

The technical design: architecture, components, data model, API contracts, dependencies. This is where "how" gets decided — deliberately, before coding, so the agent doesn't make architecture decisions by default. Plans are checked against the constitution (a "simplicity gate" rejects over-engineered designs) and the spec (every requirement must be covered).

4. Tasks

The plan decomposes into ordered, developer-ready tasks, each with its own acceptance criteria. [P] markers flag tasks that can run in parallel — the lever that makes multi-agent execution possible. Task Master specializes in this stage, turning a PRD into a structured tasks.json that agents can execute item by item.

5. Implement

Only now does the agent write code — and it writes it against the contract built in stages 1–4. Tests-first ordering is common: write the failing test, implement, converge. After implementation, a verification pass compares the codebase against the spec and appends anything unbuilt as new tasks.

The 2026 open-source landscape

The spec-driven ecosystem exploded into one of the fastest-growing corners of open source. As of mid-2026, the star counts are themselves a story — Superpowers at ~230k, GitHub Spec Kit at ~115k, OpenSpec at ~55k, BMad at ~50k. (Treat star counts as hype signals, not quality verdicts — several repositories in this space show inflated growth.)

| Project | Model | Best for | |---|---|---| | GitHub Spec Kit | Constitution-driven workflow, slash commands | Teams and individuals wanting the standard, agent-agnostic workflow | | OpenSpec | Lightweight delta specs, 4 commands | Brownfield projects; fastest on-ramp to SDD | | BMad Method | Virtual agile team of specialist agents | Full-lifecycle product work with traceability | | Superpowers | Execution discipline via skills | Teams that have a plan but need the agent to follow process | | Task Master | PRD → structured tasks | Decomposing requirements into executable task lists | | Spec Kitty | Governed lifecycle + kanban | Repos that want review gates and a visual dashboard | | SpecD | Compiled context, deterministic merge | Professional teams; multi-repo systems | | specdd | Single skill file | Individuals wanting SDD with zero setup |

Each of these gets a full guide in this cluster: Spec Kit, OpenSpec, BMad, Superpowers, Task Master, Spec Kitty, SpecD, and specdd.

The most interesting trend of 2026 is fusion: projects like superspec and spec-superflow bridge OpenSpec's planning with Superpowers' execution discipline, targeting the "planning-execution gap" that critics identify as the #1 failure mode of AI-generated PRs.

The debate: is the spec scaffolding or the source of truth?

There is a genuine philosophical split in the community. GitHub Spec Kit takes the strong position: code serves the spec — the spec is the single source of truth, and code is its projection. If they diverge, the code is wrong. Superpowers treats specs more like scaffolding: the brainstorm and design phases matter, but the discipline that actually produces working software is the execution layer — TDD, review gates, subagents.

Where you land depends on your failure mode. If your problem is agents drifting from requirements, treat the spec as truth. If your problem is agents writing sloppy, untested code, what you need is execution discipline. See the full discussion in Spec-Driven vs Vibe Coding.

Getting started: your first spec-driven week

You don't need to adopt a full framework on day one. The minimal viable spec-driven loop:

Write the spec for your next feature in a docs/specs/ folder: what, why, and 3–5 numbered acceptance criteria. No implementation details.
Plan in the open: write the architecture approach and API surface before touching code.
Decompose: break the plan into 5–15 tasks, each with acceptance criteria.
Implement against the contract — then review the diff against the spec, not against vibes.

If you like the loop, adopt a tool. Start with OpenSpec for the lightest on-ramp, or GitHub Spec Kit if you want the workflow the industry is standardizing on. Once specs exist, pair them with execution discipline from Superpowers, and run it all in parallel agent workflows to get the full 10x.

Ready to dive deeper?

GitHub Spec Kit guide — the standard workflow, command by command
OpenSpec guide — delta specs and the 4-command loop
BMad Method guide — the full-lifecycle virtual team
Superpowers guide — execution discipline that makes specs hold
Spec Kit vs OpenSpec vs BMad — how to choose
Spec-Driven vs Vibe Coding — the case for discipline