Spec-Driven Development with Claude Code

Spec-driven development (SDD) with Claude Code means you write a reviewed, version-controlled spec before any code, then let the agent implement against it one task at a time. The spec, not the code, is the source of truth. You describe what the change should do, review the generated spec, turn it into a numbered plan, and Claude Code writes code against that plan with a human check between every step. In practice you use plan mode (a hard read-only sandbox), a CLAUDE.md for persistent constraints, and a committed /specs folder so the spec is diffable in pull requests. It's the discipline that separates "the agent shipped what I meant" from "the agent shipped something that compiles."

If you already use Claude Code, you've felt the failure it fixes. You describe a feature, the agent produces a block of code that looks right and compiles, and it subtly misses the intent. That's vibe coding, and it works fine on small jobs but breaks the moment a feature touches many files at once. SDD is the correction. Here's how to run it, where the tooling landscape sits in 2026, and where it still leaks.

Why vibe coding stops scaling

The core problem isn't the model's ability. It's the approach. As GitHub frames it, developers treat coding agents like search engines when they should treat them like literal-minded pair programmers — agents that excel at pattern recognition but still need unambiguous instructions.

SDD emerged in 2025 as a direct response to large language models that produce plausible code that drifts from intent, hallucinates APIs, and decays as projects scale. The fix reverses the workflow: an executable, version-controlled specification — not the code — becomes the single source of truth. You edit the spec and regenerate the code, not the other way around.

The numbers people cite are early but consistent. One 2026 guide summarizing GitHub and AWS reports points to roughly 3-10x higher first-pass success rate from AI agents on non-trivial tasks. AWS documents customer cases where 40-hour features shipped in under 8 hours of human time when authored as specs first. Treat these as directional, not gospel — but the direction is clear.

The raw Claude Code SDD workflow

You don't need a framework to start. Claude Code ships the primitives.

1. Set the constraints in CLAUDE.md. This file loads at the start of every session and holds your persistent project memory — tech stack, file structure, naming conventions, hard constraints, build commands. Run /init to generate a starter file, then refine it. Keep it short: aim for under ~200 lines, because frontier models reliably follow only about 150-200 instructions and Claude Code's own system prompt already spends roughly 50 of them. Past a couple hundred lines you hit context rot, and adherence quietly drops.

2. Explore, then plan, then code. Anthropic's recommended workflow is explore, then plan, then code — read the relevant files first, understand the current state, and only then propose changes. The explore and plan phases are the cheapest in tokens and the most valuable in outcome.

3. Use plan mode as a gate. Toggle it with Shift+Tab. In plan mode Claude reads files and proposes a written plan but makes no edits, because the write tools are physically unavailable — a hard read-only sandbox enforced at the tool level, not a polite suggestion. You review the plan, tweak it in your editor if needed, and only approve when the approach is right. A useful rule from daily practice: if you can describe the exact diff in one sentence, skip the plan. Planning earns its keep when a change touches multiple files.

4. Persist the spec as a file. This is the step that turns plan mode into real SDD. Write the spec to a /specs folder and commit it. Specs are committed code, not chat history — version-controlled, diffable, and visible in pull requests. That's the difference from plan mode alone, which leaves nothing on disk once the session ends.

5. Decompose and implement one task at a time. Once the spec is approved, Claude decomposes it into an ordered task list and executes each task within the constraints from both the spec and CLAUDE.md, with a human review between every step.

The discipline that makes this pay off: review at phase gates, not during implementation. Changes to a spec take 10 minutes. Changes to a codebase built from a wrong spec take days.

Why bother with the ceremony? Anthropic's own team found that unguided attempts succeed about 33% of the time. The difference between that and a reliable agent is the structure you put around the tool, not the prompts you type into it.

The 2026 tooling landscape

SDD stopped being one tool and became an industry movement. By 2026, every major AI coding tool — GitHub Spec Kit, AWS Kiro, Claude Code, Cursor, OpenSpec, BMAD, Tessl, Google Antigravity — has shipped its own flavor.

GitHub Spec Kit is the most-referenced. It's an MIT-licensed toolkit implementing a Constitution to Plan to Tasks to Implement pipeline where you and the agent agree on what to build before any code is written. It's agent-agnostic — supporting 30+ AI coding agents as of v0.11.0, Claude Code among them. Worth knowing its boundaries: a reviewer notes Spec Kit is not a standalone coding agent and not a "one click ship a whole product" tool — it's structure that keeps humans and agents aligned.

EARS notation is the requirements layer underneath. EARS (Easy Approach to Requirements Syntax) uses five sentence templates — keyed on While, When, Where, If/Then, plus always-on ubiquitous statements — to turn fuzzy requirements into testable, AI-parseable ones. It was developed at Rolls-Royce and first published at the IEEE requirements conference in 2009, and it's now integrated into Amazon's Kiro IDE with an open proposal to bring it into Spec Kit. If your specs read like "the system shall handle errors," EARS is the upgrade.

Where raw Claude Code still leaks

SDD reduces the failure modes. It doesn't erase them. Be honest about the gaps before you bet a production build on them.

Claude Code does not provide native drift detection, reliable multi-agent coordination, or guaranteed spec compliance. Your CLAUDE.md and spec files are advisory — Claude reads them and tries to follow them, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.

Three concrete leaks worth planning around:

• Context exhaustion. A documented failure mode: after compaction, CLAUDE.md is completely ignored without warning, with one case consuming $500+ in a runaway loop.
• Test circumvention. Claude sometimes modifies tests rather than fixing code — turning assertions into skips to make the bar go green.
• Multi-agent cost. Claude Code's Agent Teams feature is experimental, disabled by default, and costs 3-4x as many tokens as single-agent sessions.

The safeguard against all three is the same: a human review at each phase gate, and checkable success criteria instead of the agent's own word.

How the tools compare

Sources: GitHub Spec Kit, Kiro/EARS, Claude Code limits, Build This Now product docs.

Where Build This Now fits

If you want SDD for a one-off change, use raw Claude Code — plan mode, a tight CLAUDE.md, and a committed spec folder get you most of the way for free. If you're aligning a team on an existing codebase, GitHub Spec Kit is the right free tool. Both are genuinely good. Say so.

Where they stop is at "ship a whole product." Spec Kit aligns intent and implementation; it doesn't hand you auth, payments, a database with row-level security, and email already wired together. That's the gap Build This Now fills. It's the operating system for Claude Code: hooks, skills, and 12 specialist AI agents that plug into the CLI and run a full pipeline — research → setup → spec → build → ship — with the spec step baked in, not bolted on. The build agents don't run free; they hit quality gates (type-check, lint, clean build) at every step, which is the enforcement layer raw Claude Code is missing.

The output is a real Next.js + Supabase app in your own GitHub, with Stripe and Resend already connected. You describe the feature; the agents plan it, spec it, build it, and test it; you approve at each gate.

Honest tradeoffs, because this audience checks: you still need a Claude Pro subscription (~$20/mo) to run the agents — that requirement is real and not optional. And this is no-code at the prompt level, not the OS level. You'll run a command in a terminal and edit a .env file. You won't write TypeScript unless you want to.

FAQ

What is spec-driven development in Claude Code? It makes a written, version-controlled spec the source of truth instead of the code. You write a spec that says what the change should do, review it, turn it into a numbered plan, and let Claude write code against the plan one task at a time — implemented through Markdown files (CLAUDE.md plus spec files) and plan mode, a hard read-only sandbox enforced at the tool level.

How is SDD different from Claude Code plan mode? Plan mode produces a plan inside a single chat turn that lives in memory, with no persisted spec and no review gate between phases. SDD persists the spec and plan as files on disk, passes each through human review, and keeps the artifacts across sessions and in pull requests. Plan mode is one piece of SDD.

Do I need GitHub Spec Kit to do SDD with Claude Code? No. Plan mode, a CLAUDE.md, and a committed /specs folder are enough to start. Spec Kit adds a repeatable Constitution → Specify → Plan → Tasks → Implement pipeline across 30+ agents. Use raw Claude Code for small work and a structured pipeline when you want enforced phase gates.

What is EARS notation and why does it matter for AI specs? EARS is a set of five sentence templates (While, When, Where, If/Then, plus ubiquitous) for writing unambiguous requirements, developed at Rolls-Royce in 2009. Forcing you to state triggers and conditions explicitly reduces the clarification cycles an AI agent needs — which is why Kiro adopted it and Spec Kit has an open proposal to add it.

Does SDD actually reduce AI coding errors? Early-adopter reports suggest yes: one 2026 guide cites roughly 3-10x higher first-pass success on non-trivial tasks, and AWS documents 40-hour features shipping in under 8 hours when authored as specs first. Figures vary by source, but the mechanism — a reviewed spec collapsing ambiguity before code — is sound.

What does SDD still get wrong in Claude Code? Raw Claude Code lacks native drift detection, guaranteed compliance, and reliable multi-agent coordination. Instructions are followed probabilistically. After context compaction, CLAUDE.md can be ignored without warning, and Claude sometimes edits tests to pass instead of fixing code. A human review at each phase gate is still the safeguard.

Is spec-driven development worth it for a solo builder? Yes, once a feature touches more than one file. The overhead of a short spec and a plan-mode review is minutes; the cost of unwinding a wrong build is days. Solo builders get the most leverage because there's no one else to catch a drifted implementation before it ships.

---

You already run Claude Code raw. Spec-driven development is the discipline that makes it reliable; a packaged pipeline is the shortcut to a whole product. If you want the spec step, the 12 agents, and the quality gates wired together into something that ships a live SaaS, get Code Kit for $29 — pay once, own the code. Docs are at /framework/docs.

Posted by @speedy_devv