How to Use Spec-Driven Development with Claude Code: Complete Tutorial
By Braincuber Team
Published on May 21, 2026
Spec-driven development with Claude Code is the answer when vibe-coding hits a wall. Vibe-coding works fine on small jobs where you describe a change, the agent writes it, and you check the result. The trouble starts when a feature touches many files at once. By then, the hard part is the design decision, not the implementation. This complete tutorial is a step by step beginner guide to spec-driven development, covering three open-source setups that run this workflow inside Claude Code: Superpowers, GitHub Spec Kit, and BMAD-METHOD. By the end of this guide, you will have a fully functional AI coding workflow with human review gates between every phase.
What You'll Learn:
- What spec-driven development is and why it matters for complex features
- How spec-driven development differs from Claude Code built-in plan mode
- Step by step guide to installing and using Superpowers for solo work
- How to set up GitHub Spec Kit for cross-team spec review
- BMAD-METHOD workflow with role-agents for multi-developer teams
- Decision framework to choose the right tool for your project
What Is Spec-Driven Development?
Spec-driven development is a workflow built on three documents in order: one that tells what a change should do, a plan that specifies the steps, and code written against the plan, with a human review between every pair.
A spec is a short document, written in plain language before any code, that says what a change should do. Take a feature like "let users export their data." A spec for it pins down the answers an agent would otherwise guess at. It lists supported file formats, the delivery mode, the behavior during a half-finished export, and the parts of the feature that are intentionally left out.
The plan is the next document. It breaks the spec into numbered tasks that the agent can work on one at a time, each task naming a file, a change, an order, and a test. Where the spec answers "what," the plan answers "in what steps." The code comes last, written against the plan one task at a time.
Gate 1: Spec Review
Review the spec before it becomes a plan. Catches scope creep and wrong-root-cause framings before any code is written.
Gate 2: Plan Review
Review the plan before it becomes code. Catches half-finished implementations and conflicting patterns.
Gate 3: Code Review
Review the code before it merges. Catches plans that read fine but break on the first failing test.
Human Review Between Every Pair
Three documents, three review gates. Each step passes human review before the next phase starts.
How Spec-Driven Development Differs from Plan Mode
You may have used Claude Code built-in plan mode (press Shift+Tab twice to enter it) and wondered why this is different. Plan mode produces a plan inside a single chat turn. The plan lives in memory, with no persisted spec and no review step between phases.
Spec-driven development persists the spec and the plan as files on disk. Each one passes a human review before the next phase starts, and the artifacts survive across sessions. Plan mode compresses two phases of software development into one chat turn. That works on small jobs and fails as soon as the codebase grows and starts serving real users.
| Feature | Plan Mode | Spec-Driven Development |
|---|---|---|
| Spec Document | Not persisted | Written to disk |
| Plan Document | In memory only | Written to disk |
| Human Review | None between phases | Between every pair |
| Session Survival | Lost on new session | Persists across sessions |
| Best For | Small jobs, single files | Complex features, 4+ files |
Why Vibe-Coding Hits a Wall
Vibe-coding works on prototypes, single files, and throwaway scripts. It gets worse in real applications with users to answer to and in existing large codebases. The line worth drawing is at about 4 files. Any change touching that many files needs a spec, as do any refactor with a coherent end state, or any task where "what should this do exactly?" is the hard part.
The failure has a clear cause. A vague prompt like "add photo sharing to my app" makes the model guess at thousands of unstated requirements. Take a single one of those requirements: notification preferences. The product manager assumes per-channel toggles. The backend builds an on/off switch. The frontend assumes OS-level integration. Four reasonable readings of three words, four different products.
| Failure Mode | What Goes Wrong | Caught At |
|---|---|---|
| Scope creep mid-task | Agent expands the feature past the original ask | Spec review |
| Half-finished implementations | Agent declares done at 80% with stubs and TODOs | Plan review |
| Conflicting patterns | Agent picks a different pattern than the rest of the codebase | Plan review |
| Wrong-root-cause fixes | Agent patches a symptom instead of the underlying bug | Spec review |
| Plans that break on contact | Plan reads fine, but does not survive the first failing test | Code review |
Break-Even Point
The spec phase costs hours of writing before any code runs, and the first few features feel slower than vibe-coding. The break-even point typically comes around the fourth or fifth feature. By then, the specs are catching design mistakes you would otherwise have shipped and rewritten a week later.
Superpowers: The Lightest Option
Superpowers is a Claude Code plugin by Jesse Vincent (obra/superpowers, MIT license), with around 194k stars on GitHub. It ships a set of skills that hold Claude Code to the spec-driven loop instead of letting it jump straight to code. It is the lightest of the three frameworks and the one recommended for day-to-day solo work.
Install Superpowers
Install it through Claude Code official plugin marketplace. Run /plugin install superpowers@claude-plugins-official inside Claude Code. A SessionStart hook auto-loads the using-superpowers skill, so the workflow is active the moment you start typing. There is nothing to wire up per project.
Brainstorm to Spec
Open Claude Code and describe what you want in plain language. The brainstorming skill takes over and asks ten or so questions back. Two human review points land here: the design review where you confirm your answers match what you want, and the spec review where you read the file Claude has written and approve it before any plan work begins.
Convert Spec to Plan
Run the writing-plans skill. It reads the approved spec and writes a plan file with four parts: a definition of what Done means, a file map of touched files, a user journey through the demo path, and a numbered task list of checkbox sub-steps. Review the plan, push back on tasks that look out of order or too coarse, and approve.
Execute Plan with Subagents
Run subagent-driven-development. For each task in the plan, the skill writes a failing test, writes the code to pass it, refactors, and dispatches a code-review subagent that reads the diff cold. If the reviewer flags an issue, the loop fixes it before moving to the next task.
Request Full-Diff Review
Once the plan is done, run requesting-code-review. A fresh subagent reads the whole diff against the spec and the plan, and posts a review. Take the suggestions before merging. When a task reveals a contradiction with the spec, the loop stops and asks.
| Skill | What It Does |
|---|---|
| brainstorming | Talks through the design with you and produces the spec document |
| writing-plans | Turns the approved spec into a numbered task list |
| subagent-driven-development | Executes the plan one task at a time, with test-first cycle and code-review subagent |
| requesting-code-review | Runs an independent code-review subagent over the full diff before merge |
When Superpowers Is the Wrong Choice
Superpowers fits solo work on a single repo. It struggles with multi-repo features and with work that needs clear role separation. One developer noted that even small tasks like CSS changes can take forever with subagents spinning up. The fix is to skip Superpowers for tiny changes and use it only for features touching 3 to 5 files.
GitHub Spec Kit: Cross-Team Spec Review
Spec Kit is the choice when the spec has to outlast any single Claude Code session. It is also the right pick when people who never open Claude Code need to read the spec. Spec Kit is a GitHub project (github/spec-kit, MIT license), maintained by GitHub itself, with over 100k stars. It ships a CLI plus a workflow that runs the same way across every major AI coding agent.
Install GitHub Spec Kit
There is no official PyPI package yet, so install the CLI from the Git tag with uv. Run uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z. Replace vX.Y.Z with the current release tag. The package is specify-cli, and the command it registers is specify.
| Slash-Command | Type | Description |
|---|---|---|
| /speckit.constitution | Core | Writes the project rules that every later artifact has to follow |
| /speckit.specify | Core | Produces the spec |
| /speckit.plan | Core | Produces the architecture document |
| /speckit.tasks | Core | Produces the numbered task list |
| /speckit.taskstoissues | Core | Turns those tasks into GitHub issues |
| /speckit.implement | Core | Works the tasks one at a time |
| /speckit.clarify | Optional | Asks the user follow-up questions when the spec has gaps |
| /speckit.analyze | Optional | Looks for contradictions across spec, plan, and tasks |
| /speckit.checklist | Optional | Runs a quality check on the artifacts before implementation |
The separator between command group and verb is a dot, not a colon: /speckit.specify, not /speckit:specify. The artifacts these commands produce are the same spec and plan you saw in the Superpowers section, also written to disk and tracked by Git. The difference is portability: Spec Kit artifacts are designed to work with any AI coding agent, not just Claude Code, and the workflow is built for stakeholder review via GitHub pull requests.
BMAD-METHOD: Role-Based Development
Where Spec Kit organizes artifacts, BMAD organizes people. It splits the spec-to-code workflow into four phases, each run by a named role-agent. BMAD-METHOD (bmad-code-org/BMAD-METHOD, MIT license, about 47k stars) is on version 6. The acronym expands to "Breakthrough Method for Agile AI-Driven Development." It runs on top of Claude Code and other agents, and it installs as a module ecosystem.
Install BMAD-METHOD
Install BMAD with Node. Run npx bmad-method install. The six role-agents are prompt personas the user activates by name from inside the agent host. In Claude Code, that means typing the activation command BMAD installs. Check the README for the exact syntax, which shifts between releases.
| Role-Agent | Role | Phase |
|---|---|---|
| Mary | Analyst | Phase 1: Analysis (optional) |
| Paige | Technical Writer | Phase 1: Analysis (optional) |
| John | Product Manager | Phase 2: Planning |
| Sally | UX Designer | Phase 2: Planning |
| Winston | Architect | Phase 3: Solutioning |
| Amelia | Developer | Phase 4: Implementation |
The artifact set is heavier than a single spec. You get a product brief, a PRD (Product Requirements Document), a UX spec, an architecture document, and epics broken into user stories. The PRD and the architecture document together play the same role as the Superpowers spec. The split puts them across two role-agents and into a more formal format.
For small, well-scoped work, BMAD ships a "Quick Flow" track that activates Amelia directly and skips the first three phases. Quick Flow produces no PRD and no architecture document, just a short story and the code that satisfies it. It is the answer to the "this is overkill for a button change" objection.
How to Choose Between the Frameworks
| Framework | Install | Best For |
|---|---|---|
| Superpowers | /plugin install inside Claude Code | Solo work, single-repo features, long unattended runs |
| GitHub Spec Kit | uv tool install specify-cli from Git | Cross-team spec review, spec-to-code traceability |
| BMAD-METHOD | npx bmad-method install | Long-running projects, a real PM in the loop, multi-dev handoffs |
Three rules decide the choice. Use Spec Kit if the spec has to be read by people who never open Claude Code, or has to live in Git as a long-term artifact. If several people work across distinct roles, or a real PM-style stakeholder is in the loop, use BMAD. Otherwise, use Superpowers.
Key Insight:
There is a fourth option: combine Spec Kit with Superpowers. Use Spec Kit for the spec phase so the artifacts live in Git for cross-team review. Then point Superpowers subagent-driven-development skill at the Spec Kit plan file in one line of config. You get the durable spec from Spec Kit alongside the tight implementation loop from Superpowers.
Final Thoughts on Spec-Driven Development
Spec-driven development is three documents in order. The spec says what to build, the plan says in what steps, and the code follows the plan. A human review sits between every pair. Run the decision framework above to pick a framework, which for most readers will land on Superpowers. Install it and pick one feature you would otherwise vibe-code, something that touches 3 to 5 files. Run it end-to-end through brainstorm, spec, plan, and execute. One real run teaches the workflow better than any description.
Getting Started Recommendation
If you are new to Claude Code, start with the Claude Code 101 course to get hands-on experience. Then pick one feature and run it through the full spec-driven workflow. One real run teaches the workflow better than any description.
Frequently Asked Questions
What is spec-driven development in Claude Code?
Spec-driven development is a workflow built on three documents in order: a spec that tells what a change should do, a plan that specifies the steps, and code written against the plan, with a human review between every pair.
How is spec-driven development different from Claude Code plan mode?
Plan mode produces a plan inside a single chat turn in memory with no persisted spec. Spec-driven development persists both the spec and plan as files on disk, runs each through human review, and survives across sessions.
Which framework should I start with: Superpowers, Spec Kit, or BMAD?
Start with Superpowers for solo work on a single repo. Use GitHub Spec Kit when the spec needs cross-team review. Use BMAD-METHOD for multi-developer teams with distinct roles.
How do I install Superpowers in Claude Code?
Run /plugin install superpowers@claude-plugins-official inside Claude Code. A SessionStart hook auto-loads the workflow, so there is nothing to wire up per project.
What happens when the spec is wrong mid-implementation?
The loop stops and asks. In Superpowers, you edit the spec and regenerate affected tasks. In Spec Kit, run /speckit.analyze. In BMAD, a FAIL verdict sends you back to rewrite the PRD.
Need Help with AI Development Setup?
Our experts can help you configure AI coding tools, set up spec-driven workflows, and optimize your development process for maximum productivity. Get personalized guidance for your projects.