Spec-driven development with Claude Code

What Claude Code gives you out of the box

Claude Code already contains most of the pieces of a spec-driven loop. It just does not assemble them for you, and it does not protect any of them from itself.

• CLAUDE.md: a markdown file at the repository root, loaded into context at the start of every session. Conventions, commands, rules. The persistent half of any spec you keep in the repo.
• Plan mode: Shift+Tab cycles into it. Claude reads the codebase and proposes a plan without editing anything until you approve. The review-before-code half.
• MCP: /mcp lists connected servers; claude mcp add connects one. The way to give Claude something to read that is not in the working tree, including a spec it cannot write to.
• Skills and plugins: packaged instructions and tools. The way to make "read the spec before you implement" a standing rule rather than a thing you remember to type.

The lightest loop that is actually spec-driven

No toolkit, four steps, and it is what the people who kept doing spec-driven development after the tools cooled off converged on.

• Write the intent in a file, not in the prompt: specs/<feature>.md with what it must do, the constraints, the acceptance criteria, and, the part people skip, what is out of scope.
• Plan mode, questions first. Ask Claude to read the spec and the codebase, write down what it does not know, then produce a plan into a file.
• Edit the plan by hand. Answer the questions in the file, cross out what you do not want. This is the review.
• Implement one task at a time, out of plan mode, with a look between tasks.

Read specs/refunds.md and explore the codebase to see how refunds work today.
Write down every question the spec leaves open before you plan anything.
Then write an implementation plan into specs/refunds.plan.md, one task per step.
Do not edit any other file.

The questions are usually 80% useless but those 20% often do point me to stuff I have not considered. Then I edit the markdown manually or discuss some parts with the agent. "go ahead and implement"

Imanari, Hacker News, February 2026

This is GitHub Spec Kit's specify → plan → tasks → implement loop done by hand. If you want the slash commands and the constitution file, Spec Kit supports Claude Code directly, and our page on it says when the extra structure is worth it and when it is not.

Where it stops

Run the loop above for a few weeks on a real project and you will hit the same three walls the spec-driven development guide collects from other people's accounts.

Claude can edit the spec. It is a file in a directory Claude has write access to. Tell it to "bring the spec in line with what we built" and it will, which is sometimes what you want. It will also do it unasked when the spec and the code disagree and the code is easier to keep, and the diff to specs/refunds.md is the one you skim, because you are reviewing the code.

The spec is gone next session. refunds.plan.md describes one change. Next week the only thing Claude reads at startup is CLAUDE.md, and CLAUDE.md is prose about how to work, not a list of what the product must do. It also has a practical ceiling:

I find the sweet spot is ~750 lines for each file. Planning files can max out at 1,500 lines if needed or otherwise broken up into individual phases.

waldopat, Hacker News, February 2026

Nothing marks what was decided. When the spec leaves a gap, Claude fills it, in confident prose, and the guess sits in the plan next to your decisions with nothing to tell them apart. Why the agent guesses goes through what that looks like across three agents; the short version is that it is not sycophancy, it is that the model had nothing to disagree with.

Handing Claude Code a spec it cannot rewrite

The fix is to move the spec out of the working tree and serve it over MCP, so Claude reads it the way it reads a database: as something it queries, not something it edits. Entalpa is that server. Two commands connect it:

claude mcp add --transport http entalpa https://api.entalpa.com/mcp
# then, inside Claude Code:
/mcp   # select entalpa, approve the browser login

Or install the plugin, which adds the MCP connection and the Entalpa skill together. The skill is what makes "read the requirements before you implement, and keep the links to them" a standing rule instead of a prompt:

claude plugin marketplace add entalpa/entalpa-mcp --sparse .claude-plugin plugins
claude plugin install entalpa@entalpa-plugins

The full setup, including what to do when the browser does not open, is on the Claude Code setup page. What changes in the session is the shape of the spec Claude is reading.

• It persists. The project's stakeholders, stories and requirements are there next session without anyone re-pasting them, and Claude pulls the ones relevant to the task rather than a 750-line file.
• Locked requirements are not offered to the model. When Entalpa regenerates requirements, a locked one is filtered out of the set it is given: chosen_reqs = [req for req in existing_reqs if not req.lock]. There is no rewrite to catch in review because the rewrite is not produced.
• Open questions are objects. What the description left undecided is listed as undecided. Claude sees a gap as a gap.
• Traceability survives the implementation. A requirement links to the story it came from and the stakeholder who needed it, so "what does this change affect" has an answer before Claude touches a file.

Keep CLAUDE.md. It is still the right place for how to work in this repository: test commands, style, the branch model. The requirements move out; the rules of engagement stay. Reading and writing the project over MCP never spends credits; Entalpa's own generation does.

A CLAUDE.md that points at the spec

Four lines in CLAUDE.md make the connection a habit rather than a thing you remember. Adjust the project name; the rest is the rule.

## Requirements

The product requirements live in Entalpa (MCP server `entalpa`, project "Refunds"),
not in this repository. Before implementing anything, read the user story and the
requirements it links to. Do not implement behaviour that no requirement describes;
if the task needs one that is missing, say so and stop rather than inventing it.

That last sentence is the one that does the work. It converts the failure mode from "Claude guessed" into "Claude asked", which is the entire difference between a spec-driven session and a well-documented vibe-coding one.

Questions this raises