Spec-Driven Development with Claude Code, Shown in Action

Spec-driven development with Claude Code means you write a short spec — what to build, the rules it must follow, how you'll know it's done — get it approved, and only then let the agent write code against that spec as a contract. You review the plan, not just the result. It's the opposite of "just make it work and hope," and it's the single biggest quality lever when you build with an agent.

What is spec-driven development with Claude Code?

A spec is a short, plain document you write before any code is touched. It says three things: what you want, the constraints it must respect, and the test for "done." With Claude Code, you draft the spec (often with the agent's help), read it, fix the assumptions that are wrong, approve it, and then tell the agent to build exactly that.

The order matters. In spec-driven development, the spec is not documentation you write after the fact — it's the instruction the agent follows. When the agent drifts, you point back at the spec instead of re-explaining from memory. When you start a fresh session, the spec carries the context the context window lost.

This is a human-in-the-loop checkpoint placed where it's cheapest: before code exists. Catching a wrong assumption in a 200-word spec costs a sentence. Catching it after the agent has wired it through six files costs an afternoon.

Spec-driven development vs vibe coding

The honest contrast is with vibe coding: you describe a feeling, the agent generates code, you run it, and if it looks right you keep going. Vibe coding is genuinely good for throwaway prototypes, one-off scripts, and "show me roughly what this could be." It's fast because there's no checkpoint.

It falls apart on anything you have to maintain. With no agreed spec, "done" is whatever the agent produced, the agent silently invents decisions you never made, and review happens at the end when changes are expensive. Spec-first moves the decision to the front, where a coding agent is cheapest to redirect.

Neither is "correct" everywhere. The skill is knowing which mode the task deserves — and not vibe-coding a payment flow because it felt faster.

How do you write a spec for Claude Code?

Keep it short enough to read in two minutes. A spec that nobody reads is worse than no spec. In practice ours have four parts:

• Goal — one or two sentences on what we're building and why.
• Constraints — the rules the build must respect: existing patterns, the stack, files it may and may not touch, anything that's off-limits.
• Plan — the steps, in order, with dependencies noted.
• Done — the checklist that proves it works (build passes, this route renders, this test is green).

Ask Claude Code to draft this from your description first. Reading and correcting a draft is faster than writing from a blank page, and the agent surfaces edge cases you'd forget. Then you do the part only a human can: say "no, not like that," fix the wrong assumption, and approve.

For larger jobs the spec doubles as a task list, and we hand independent steps to subagents inside an agentic workflow. The spec keeps them coordinated — each task references the same contract, so parallel work doesn't drift apart. We go deeper on the whole supervised loop in the guide to building websites with Claude Code.

Spec-driven development with Claude Code, in action

Here's the loop on a real-shaped task: migrating a content section to a new data source — the kind of job that touches storage, a sync step, and a couple of integration points.

Vibe-coding version. You tell the agent "move the blog posts to the new source." It starts editing. Within the hour you have partial progress and rising doubt — no single change looks wrong, but you can't tell if the whole thing holds together. You stop, unsure what's safe to keep.

Spec-first version. First you ask Claude Code to research the current and target setup and report back — no edits yet, just understanding. From that you write a short spec: goal, the constraint that old URLs must keep working, the ordered steps, and a "done" checklist (build green, every old post route still resolves, the feed renders). You read it, catch that one field name was guessed wrong, fix it, approve.

Then the agent builds against the spec. Each step ends the same way: run the checks, and if they pass, commit that step on its own. If a session goes sideways, you don't reconstruct anything from memory — you re-open the spec, see which step you're on, and continue. The spec is the thing the agent forgets but you keep.

The difference isn't that the agent writes better code. It's that you stayed in control of the decisions, and every change is small enough to review and undo. For why a studio's edge in the AI era is this supervised build loop, see our note on the website-studio moat in the AI era, and the team-level mechanics in CLAUDE.md progressive disclosure for fast teams.

When should you skip the spec?

Skip it when the work is genuinely throwaway: a quick script you'll run once, a rough prototype to see if an idea is worth pursuing, a tiny one-file change where the whole diff fits on a screen. Forcing a spec there is bureaucracy, and bureaucracy is the fastest way to make people stop writing specs at all.

Use a spec the moment the work has to survive: anything multi-file, anything that touches data or money, anything someone else will maintain, anything where "wrong" is expensive to find later. The tell is dependency. If step three depends on step one being right, you want that written down before the agent runs. In our experience the cost of a spec is a few minutes, and the cost of skipping one on the wrong task is the rest of the day.

FAQ

Is spec-driven development slower than vibe coding?

It feels slower for the first ten minutes because you write and approve a spec before any code appears. Total time is usually shorter on real work, because you spend far less of it on rework, debugging tangled changes, and rebuilding context after a session resets.

Do I need subagents to use spec-driven development with Claude Code?

No. Subagents help you run independent steps in parallel, but the value comes from the spec itself — a clear goal, constraints, and a "done" checklist. A single agent following an approved spec already beats vibe coding on anything you have to maintain.

What should a Claude Code spec always include?

A goal, the constraints the build must respect, the ordered steps with their dependencies, and a checklist that proves it works. The "done" checklist is the part people skip and the part that matters most — without it, "finished" means whatever the agent happened to produce.

How is this different from just writing detailed requirements?

A spec is approved before code and referenced during the build, so it acts as a live contract, not a document you file and forget. You correct the agent against the spec instead of from memory, which is what keeps a long or interrupted session on track.

Can Claude Code write the spec for me?

Yes, and it should draft it — reading and correcting a draft is faster than starting from blank. But you have to do the human part: reject wrong assumptions, fix the constraints, and approve it. The point of spec-first is that a person owns the decisions before the agent commits to them.