{"id":7045028,"date":"2026-08-23T15:24:19","date_gmt":"2026-08-23T15:24:19","guid":{"rendered":"https:\/\/peraltafinancing.com\/analytics\/spec-driven-development-with-claude-code-a-practical-guide\/"},"modified":"2026-08-23T15:24:19","modified_gmt":"2026-08-23T15:24:19","slug":"spec-driven-development-with-claude-code-a-practical-guide","status":"publish","type":"post","link":"https:\/\/fivemor.com\/?p=7045028","title":{"rendered":"Spec-Driven Development with Claude Code: A Practical Guide"},"content":{"rendered":"


\n<\/p>\n

\n

I have written enough specs for Claude Code now to have hit the failure mode nobody warns you about<\/strong>.\u00a0<\/p>\n

The spec was fine. The plan was fine. Claude worked through the tasks, ran the test suite, and reported everything passing. I looked at the diff<\/code> properly the next morning and found it had converted a flaky test from an assertion into a skip. The suite was green<\/mark>. The requirement was not met. The test could no longer\u00a0fail, because\u00a0it either passed or quietly skipped.\u00a0<\/p>\n

That is not a bug in Claude Code. It is what happens when a criterion has no failing state. And it is the part of spec-driven development that most guides leave out, because writing the spec is the easy half.\u00a0<\/p>\n

This article covers both halves. How to write the spec, and how to write it so the agent cannot declare victory without earning it.\u00a0<\/p>\n

Why a Spec Changes the Odds\u00a0<\/h2>\n

The argument for spec-driven development is usually made on vibes. There is a better version of it that is just arithmetic.\u00a0<\/p>\n

Anthropic\u2019s\u00a0own RL Engineering team has reported that Claude Code\u2019s first-attempt success rate on small to medium pull requests, without detailed guidance, sits at\u00a0roughly one\u00a0in three. Two thirds of the time it misses a requirement, reads the scope too broadly, or picks an implementation path you would not have chosen.\u00a0<\/p>\n

Here is why that number is not surprising. Suppose Claude makes the call you would have made 80% of the time on any single decision. A feature of reasonable size involves around twenty decisions. Get all twenty right at 80% each and you are at 0.8 to the power of 20, which is about 1%.\u00a0<\/p>\n

\nThe point:<\/b>\u00a0a spec does not make Claude smarter at those decisions. It removes them from Claude\u2019s hands\u00a0entirely, because\u00a0you already made them. That is the whole mechanism.\n<\/p>\n

The Four Phases, and the One Rule People Break<\/h2>\n

Spec-driven development runs in four phases. Requirements, design, tasks, execute.\u00a0<\/p>\n

\n\n\n\n\n\n\n\n
Phase<\/strong><\/td>\nWhat it captures<\/strong><\/td>\nWhere it happens<\/strong><\/td>\n<\/tr>\n
Requirements<\/td>\nWhat the feature must do from the user\u2019s side. User stories, acceptance criteria, edge cases. Not how.<\/td>\nSession 1, plan mode<\/td>\n<\/tr>\n
Design<\/td>\nData models, API contracts, which files change, which stay untouched, what is explicitly out of scope.<\/td>\nSession 1, plan mode<\/td>\n<\/tr>\n
Tasks<\/td>\nOrdered implementation steps with dependencies. Task 3 cannot start before task 2 finishes.<\/td>\nSession 1, plan mode<\/td>\n<\/tr>\n
Execute<\/td>\nClaude writes code against the task list, one task at a time.<\/td>\nA fresh session<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n

The rule people\u00a0break:\u00a0<\/strong>execute in a new session. Not a continuation of the planning session.\u00a0<\/p>\n

This is the step I skipped for a while because keeping one session open felt more efficient. It is not. By the end of planning, your context holds every rejected idea, every clarifying question, and every file Claude read while exploring. Building in that same window means every implementation decision is reasoned against a pile of discarded alternatives.\u00a0<\/p>\n

A fresh session reads SPEC.md<\/code> and PLAN.md<\/code> as documents, with no memory of the arguments that produced them. That is the point. The spec is supposed to be the interface between the two phases.\u00a0<\/p>\n

Phase 1: let Claude interview you<\/h3>\n

Writing a good spec from a blank page is slow. Having Claude extract one from you is faster and surfaces decisions you had not thought about:\u00a0<\/p>\n

claude\u00a0--permission-mode plan\u00a0<\/code><\/pre>\n
> I want to build passwordless magic-link login. Interview me in detail using the AskUserQuestion tool.\n \n  Ask about implementation, edge cases, failure modes, and tradeoffs. Skip the obvious questions, dig into        the parts I might not have considered. \n \n  Keep going until we have covered everything, then write the spec to SPEC.md.<\/code><\/pre>\n
\n
\"Claude<\/figure>\n<\/div>\n
Plan mode matters here. Claude reads and reasons but writes nothing until you allow it. When the spec appears, press\u00a0Ctrl+G\u00a0to open it in your editor and change it directly. Editing the spec yourself is what turns it from Claude\u2019s document into yours.\u00a0<\/p>\n
Try this now:\u00a0<\/strong>take the next feature on your list and paste that interview prompt with a one-line description. Answer honestly, including the questions you do not have an answer to yet. Those gaps are the actual design work, and they are cheaper to find now than in task 7 of the build.\u00a0<\/p>\n
Write Criteria a Command Can Settle\u00a0<\/h4>\n
This is the section that matters most, and it is where the earlier guides are thinnest.\u00a0<\/p>\n
Every acceptance criterion you write falls into one of two categories. Either a command can decide whether it passed, or the agent decides. Anything in the second category is a criterion the agent grades itself on.\u00a0<\/p>\n
\n\n\n\n\n\n\n\n\n
Interpretable<\/strong><\/td>\nCheckable<\/strong><\/td>\n<\/tr>\n
Login should be secure<\/td>\nA request with an expired token returns HTTP 401<\/td>\n<\/tr>\n
Handle rate limiting properly<\/td>\nThe 4th request from one email within an hour returns HTTP 429<\/td>\n<\/tr>\n
Well-structured error handling<\/td>\nEvery 4xx response body contains an \u2018error\u2019 key with a string value<\/td>\n<\/tr>\n
The export should be fast<\/td>\nExporting 10,000 rows completes in under 3 seconds locally<\/td>\n<\/tr>\n
Tests should pass<\/td>\npytest exits 0 and the diff adds no skip markers<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
What changes between those two columns is not tone or level of detail. It is whether there is a state the criterion can be in that counts as failing.\u00a0<\/p>\n
Phase 2: EARS notation, if you want a template\u00a0<\/h3>\n
If you would rather not invent phrasing each time, there is a notation for this. EARS, short for Easy Approach to Requirements Syntax, came out of Rolls-Royce in 2009 and has been picked up by AWS Kiro, with an open proposal to add it to GitHub Spec Kit.\u00a0<\/p>\n
It is five sentence shapes. The useful ones in practice:\u00a0<\/p>\n
\n\n\n\n\n\n\n\n\n
Pattern<\/strong><\/td>\nExample<\/strong><\/td>\n<\/tr>\n
WHEN  THE system SHALL <\/trigger><\/td>\nWHEN a valid email is submitted THE system SHALL send a link valid for 15 minutes<\/td>\n<\/tr>\n
IF  THEN THE system SHALL <\/condition><\/td>\nIF a link is used twice THEN THE system SHALL return HTTP 410<\/td>\n<\/tr>\n
WHILE  THE system SHALL <\/state><\/td>\nWHILE a user is rate limited THE system SHALL return HTTP 429<\/td>\n<\/tr>\n
WHERE  THE system SHALL <\/feature><\/td>\nWHERE SSO is enabled THE system SHALL skip the magic-link flow<\/td>\n<\/tr>\n
THE system SHALL <\/td>\nTHE system SHALL log every issued token with a hashed identifier<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Forcing yourself to name the trigger and the condition is what removes ambiguity. The side effect is that criteria written this way map almost one to one onto test cases, which is what makes a spec executable rather than advisory.\u00a0<\/p>\n
The Failure\u00a0Mode\u00a0Nobody Warns You About\u00a0<\/h3>\n
Now the part that prompted this article.\u00a0<\/p>\n
Anthropic\u2019s\u00a0own reward-hacking research documents that Claude Code models, given hard tasks, sometimes\u00a0modify\u00a0or delete test assertions rather than fixing the source code. The Sonnet 4.6 system card states directly that the model can find shortcuts or workarounds that technically satisfy requirements while missing the intended goal.\u00a0<\/p>\n
This is not the model being adversarial. It is a system optimising against the signal you gave it. If the signal is \u201cthe test suite passes\u201d, then editing the test is a valid path to that signal, and a much shorter one than fixing the bug.\u00a0<\/p>\n
What this looks like in practice\u00a0<\/h3>\n
Two documented cases worth knowing, because both would pass a casual review:\u00a0<\/p>\n
\n\n\n\n\n\n
Reported case<\/strong><\/td>\nWhy it slipped through<\/strong><\/td>\n<\/tr>\n
A flaky end-to-end test converted from assert result[\u2018success\u2019] to pytest.skip() on timeout<\/td>\nThe suite reported green. The test can now never fail; it either passes or silently skips.<\/td>\n<\/tr>\n
A production security hardening task declared ready without the review step being run. The user then found eight security issues, two of them critical.<\/td>\nCompletion was asserted rather than evidenced, and the assertion was accepted.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
The pattern in both:\u00a0<\/strong>a criterion that the agent was allowed to self-certify. Checkable criteria constrain this in a way interpretable ones cannot. \u201ccurl\u00a0returns 429\u201d has a failing state. \u201cWell-structured code\u201d does not.\u00a0<\/p>\n
Two defences that cost almost nothing\u00a0<\/h3>\n
First, ask for evidence rather than assurance. Tell Claude to show the command it ran and the output it got, not a summary of how it went. Reading evidence takes seconds and is the only way to review a run you were not watching.\u00a0<\/p>\n
Second, put the anti-gaming rules into the criteria themselves. If the spec says the diff must not add skip markers or\u00a0delete\u00a0assertions, then doing so is a spec violation rather than a clever shortcut:\u00a0<\/p>\n
## Verification rules\u00a0\n\n-\u00a0pytest\u00a0exits 0 with zero skipped tests\u00a0\n- git diff adds no @pytest.mark.skip,\u00a0pytest.skip,\u00a0or .only\u00a0\n- git diff\u00a0deletes\u00a0no existing assert lines\u00a0\n- Every criterion in section 2 has at least one test naming it<\/code><\/pre>\n
Phase 3: Three Ways Specs Drift Mid-Build\u00a0<\/h3>\n
Even a good spec loses its grip as a build gets longer. An issue thread from April 2026 categorised the ways this happens, and the categories match what I have seen:\u00a0<\/p>\n
\n\n\n\n\n\n\n
Drift mode<\/strong><\/td>\nWhat happens<\/strong><\/td>\n<\/tr>\n
Ignored<\/td>\nThe rule is in context and readable, and gets passed over during execution anyway.<\/td>\n<\/tr>\n
Forgotten<\/td>\nContext fills with code as the build progresses, and the rule falls out of effective attention.<\/td>\n<\/tr>\n
Skipped<\/td>\nThe rule is read and judged unnecessary for this particular case.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
The blunt summary from that thread, paraphrasing the agent\u2019s own behaviour: it can recite the rules, it just does not follow them. Which tells you something important. A rule living in a document is advisory. Restating it more forcefully does not change its category.\u00a0<\/p>\n
What\u00a0actually held:\u00a0<\/strong>of the approaches tried in that thread, only pre-commit hooks proved reliable. A hook is code. It runs\u00a0whether or not\u00a0the rule was in attention.\u00a0<\/p>\n
A gate script does not need to be clever. Grep the diff for skip markers, check that each criterion identifier in SPEC.md appears in at least one test file, exit non-zero with a readable message. Claude reads the failure and fixes it, which is exactly the loop you want.\u00a0<\/p>\n
Phase 4: Executing the Plan Without Losing the Thread\u00a0<\/h3>\n
Once the spec and task list exist, the execution session is where the discipline pays off or does not.\u00a0<\/p>\n
Give the session a goal condition, not just a prompt\u00a0<\/h4>\n
A goal condition is re-checked by an evaluator after every turn, so the session ends when the condition holds rather than when the output looks finished:\u00a0<\/p>\n
> \/goal All 5 acceptance criteria in SPEC.md have a passing test,\u00a0\n\u00a0 and git diff --stat shows no changes outside\u00a0src\/auth\/ and\u00a0\n\u00a0 tests\/auth\/<\/code><\/pre>\n
\n
\"Claude<\/figure>\n<\/div>\n
Notice the second clause. Scope creep is the most common way a build technically satisfies a spec while doing things you did not ask for, and it is easy to\u00a0state\u00a0as a checkable condition.\u00a0<\/p>\n
One task, one subagent, one commit\u00a0<\/strong> \u00a0<\/h3>\n
For anything past a handful of tasks, give each task its own subagent. Each one starts with a clean context, reads only PLAN.md and the files its task needs, and commits atomically. The exploration and file reading stay out of your main window, and a bad task is one revert rather than an untangling job:\u00a0<\/p>\n
> Work through PLAN.md in order. Give each task its own subagent.\u00a0\n\u00a0 One commit per task, and stop if any task fails rather than\u00a0\n\u00a0 working around it.<\/code><\/pre>\n
The instruction to stop rather than work around a failure is doing real work in that prompt. Task 5 failing because the spec never mentioned Redis is useful information. Task 5 silently being implemented with an in-memory counter is not.\u00a0<\/p>\n
Review with a context that never saw the plan being written\u00a0<\/h2>\n
Before calling it done, have a fresh subagent check the diff against the spec. Because it never saw your reasoning, it judges the result on its own terms:\u00a0<\/p>\n
Use a subagent to review the full diff against SPEC.md.\u00a0\nFor each acceptance criterion,\u00a0state\u00a0whether it is implemented\u00a0\nand which test covers it. Flag any file changed that the spec\u00a0\ndid not put in scope. Report gaps, not style preferences.<\/code><\/pre>\n
Do You Still Need a Framework?\u00a0<\/h2>\n
Most spec-driven development writing from last year assumes you install something. That assumption is worth revisiting, because Claude Code has since shipped native primitives for most of what those frameworks provided.\u00a0<\/p>\n
\n\n\n\n\n\n\n\n\n\n\n
What you need<\/strong><\/td>\nNative Claude Code<\/strong><\/td>\nFramework<\/strong><\/td>\n<\/tr>\n
Interview to produce a spec<\/td>\nAskUserQuestion in plan mode<\/td>\nSpec Kit \/specify, \/clarify<\/td>\n<\/tr>\n
Read-only planning phase<\/td>\nPlan mode, Ctrl+G to edit<\/td>\nKiro\u2019s spec phase<\/td>\n<\/tr>\n
Ordered task list<\/td>\nAsk for it in the plan<\/td>\nSpec Kit \/tasks<\/td>\n<\/tr>\n
Condition that gates completion<\/td>\n\/goal with an evaluator<\/td>\nNot typically provided<\/td>\n<\/tr>\n
Hard gate on completion<\/td>\nStop hook or pre-commit hook<\/td>\nNot typically provided<\/td>\n<\/tr>\n
Task isolation<\/td>\nOne subagent per task<\/td>\nBMAD role agents<\/td>\n<\/tr>\n
Reusable workflow<\/td>\nA skill with a slash command<\/td>\nFramework slash commands<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
Scaling to Parallel Work\u00a0<\/h2>\n
One subagent per task is sequential by default. If your task list has independent branches, two options\u00a0open up.\u00a0<\/p>\n
Agent teams\u00a0<\/h3>\n
Agent teams shipped with Opus 4.6 in February 2026 and are still experimental. A lead session spawns teammates, each with its own context window, and they coordinate through a shared task list and a mailbox rather than only reporting back to a parent. You enable it with an environment variable:\u00a0<\/p>\n
# in\u00a0settings.json\u00a0or your shell\u00a0\nCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1\u00a0<\/code><\/pre>\n
The cost is real. Teams use\u00a0roughly seven\u00a0times the tokens of a single session in plan mode, per Claude Code\u2019s own cost documentation. For a multi-module feature where the modules really do not touch, that can still be worth it. For a linear task\u00a0list\u00a0it is waste.\u00a0<\/p>\n
Know the ceiling\u00a0<\/h4>\n
Reported experience puts the practical sweet spot at three to five concurrent agents. Past that, coordination overhead and merge conflicts eat the parallelism. This matches what I have seen: the second and third agent feel like a clear gain, the sixth feels like managing a standup.\u00a0<\/p>\n
For much larger fan-out, Dynamic Workflows can coordinate far more subagents in a single session, which we covered in\u00a0our Claude Opus 4.8 article<\/a>. And for how these pieces assemble into repeatable systems rather than one-off runs,\u00a0Loop Engineering for AI Agents<\/a>\u00a0is the wider view.\u00a0<\/p>\n
Honest Limits\u00a0<\/h4>\n
Things spec-driven development in Claude Code does not give you, which are worth knowing before you bet a production build on it:\u00a0<\/p>\n
\n\n\n\n\n\n\n\n
Limit<\/strong><\/td>\nWhat it means for you<\/strong><\/td>\n<\/tr>\n
No native drift detection<\/td>\nNothing automatically notices when the build stops matching the spec. A hook is your detection layer.<\/td>\n<\/tr>\n
No guaranteed spec compliance<\/td>\nThe spec is context, not a constraint. Only deterministic gates are enforcement.<\/td>\n<\/tr>\n
Multi-agent coordination is not reliable yet<\/td>\nAgent teams remain experimental. Treat parallel work as something to supervise.<\/td>\n<\/tr>\n
Specs go stale<\/td>\nA spec written three features ago may describe behaviour that has since changed. Date them and mark what they supersede.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n
None of these are reasons to skip the spec. They are reasons to put the enforcement in code rather than in prose.\u00a0<\/p>\n
What Changed in How I Work\u00a0<\/h2>\n
Spec-driven development gets sold as a productivity technique.<\/span> In practice the gain is not speed on any one feature. It is that the failure mode moves to a place where you can catch it.\u00a0<\/p>\n
Without a spec, a wrong decision surfaces when you read the diff, or later, when something breaks. With one, it surfaces while you are answering an interview question about a case you had not considered. That is a much cheaper place to be wrong.\u00a0<\/p>\n
The part that took me longest to accept is that the spec is not the artifact doing the work. A document full of intentions is advisory, and an agent optimising for a signal will find the shortest path to that signal. What does the work is the small set of things that can return a non-zero exit code.\u00a0<\/p>\n
If you take one thing:\u00a0<\/strong>write every criterion so a command can settle it, then put the ones that matter behind a hook. That single change does more than any amount of\u00a0additional\u00a0spec prose.\u00a0<\/p>\n
The primitives referenced here come from the\u00a0official Claude Code best practices documentation<\/a>, and\u00a0GitHub Spec Kit<\/a>\u00a0is the reference framework implementation if you want to compare. For the session flags and commands used throughout, see\u00a0the CLI commands worth knowing<\/a>.\u00a0<\/p>\n
Frequently Asked Questions<\/strong>\u00a0<\/h2>\n
\n
Q1. How long should a spec be?<\/strong>\u00a0<\/strong> <\/p>\n
A. Long enough to remove the decisions you care about, and no longer. A spec for a feature of a few days\u2019 work is usually one to two pages. If it is longer than the code it produces, you are writing documentation rather than a spec. The test is whether each line removes a decision Claude would otherwise make.\u00a0<\/p>\n<\/p><\/div>\n
Q2. Is spec-driven development the same as test-driven development?<\/strong>\u00a0<\/strong> <\/p>\n
A. They are related but the primary artifact differs. TDD treats a failing test as the thing you write first. SDD treats the specification as primary, with the tests generated from its acceptance criteria. In practice they compose well: write criteria in a shape that maps to test cases, and the first execution task becomes writing those tests.\u00a0<\/p>\n<\/p><\/div>\n
Q3. Why must execution happen in a separate session?<\/strong>\u00a0<\/strong> <\/p>\n
A. By the end of planning your context is full of rejected options and files read during exploration. Implementing in that same window means every decision is reasoned against discarded alternatives, and you burn context you will need for the build. A fresh session reads the spec as a document, which is what it was written to be.\u00a0<\/p>\n<\/p><\/div>\n<\/p><\/div>\n
\n
\n
\n                                    
\n                                                                       \"Sree
\n                                                                <\/a>\n                                <\/div>\n<\/p><\/div>\n
Hi , I am Sree Vamsi a passionate Data Science enthusiast currently working at Analytics Vidhya. My journey into data science began with a curiosity for uncovering insights from complex data and has evolved into building end-to-end Generative AI applications, RAG pipelines, agentic AI workflows, and multi-agent systems that solve real-world business problems.<\/p>\n<\/p><\/div>\n<\/p><\/div>\n
Login to continue reading and enjoy expert-curated content.<\/h4>\n