SDD with Claude Code

Spec-Driven Development with Claude Code: How to Stop AI from Guessing Your Requirements

Last spring, our Lead AI Engineer was exploring Claude Code for a Fintech project. In one of his trials, he asked Claude Code to implement late-fee calculations in an existing invoicing service. The initial code changes appeared correct and all tests passed. With no obvious issues in the implementation, he almost approved the changes.

On a second read, the lead found that fees were being charged on the full invoice amount even after a partial payment was done. Also, the grace period was counted in server time instead of the customer’s time zone and that a migration script had created an extra column without him asking for it.

The model wasn’t malfunctioning. He had given it a single-sentence instruction, and it had filled the gaps with assumptions that sounded reasonable.

This is the kind of problem spec-driven development with Claude Code is intended to address.

Spec-driven development (SDD) is the practice of specifying the intended behavior, the constraints, acceptance parameters, the proof of completion, and other criteria before an agent writes code, then keeping that document in the repository as the reference for planning, building and review.

This blog shares our team’s experience using Claude Code for spec-driven development, covering how specifications fit into the development process, what the tool can do, its limitations, and how it compares with other tools and more.

Table of Contents

What is Spec-Driven Development with Claude Code?

SDD with Claude Code is a development approach in which developers outline boundaries and acceptance criteria before asking Claude Code to code a feature. The specification then works as a guide they refer to for testing and code review.

Anthropic’s own best practices guidance has made a similar point: jumping straight to code can solve the wrong problem, which is the failure our late-fee story shows.

There are four questions a spec or specification should answer:

  • What existing behaviors should remain unchanged?
  • What behavior needs to change?
  • What boundaries must Claude Code respect?
  • What evidence will prove that the feature works correctly?

Stating constraints is critical because Claude Code can make technically reasonable decisions that the product doesn’t require at all. An agent for transaction exports could very well add a new endpoint even though the app already has an export service. A spec makes those constraints explicit.

For additional context on the approach, you can take a look at our earlier piece on spec-driven development with AI. We have covered the fundamentals there.

How SDD with Claude Code Differs from Prompt-Driven Coding and a PRD

 Factor

Prompt-Driven PRD

Spec-Driven Development

Written for Nobody, the prompt is the record Product and business stakeholders The agent and the reviewer
Level of detail Whatever fits in a chat message Goals, users, scope Behavior, constraints, non-goals, testable criteria
Lives in Chat history A wiki or ticket The repository, next to the code
Checked by Reading the output Sprint review Tests and a review as per the criteria

Claude Code Capabilities That Support Spec-Driven Development

Claude Code does not need add-on to support the development workflow because the necessary pieces ship with it. The official documentation has covered all of them in detail.

Claude Code capabilities for Spec-Driven Development

Claude Code capability

Responsibility in an SDD workflow

Plan mode Investigate the requirement and produce an implementation approach before editing code
CLAUDE.md Maintain repository-wide engineering instructions
Skills Standardize repetitive workflows like reviewing specifications
Subagents Delegate repository analysis, testing, or implementation review
Hooks Execute deterministic checks at defined points in the workflow
Git Preserve changes, review implementation scope, and link evidence to commits

Where Should the Specification Live?

Here’s an example of a repository structure our team uses for spec-driven development with Claude Code:

project/

├── CLAUDE.md

├── .claude/

│   ├── skills/

│   │   └── spec-review/

│   │       └── SKILL.md

│   └── agents/

│       └── spec-reviewer.md

├── specs/

│   └── transaction-export/

│       ├── spec.md

│       ├── plan.md

│       └── verification.md

└── src/

Each file serves a specific purpose:

  • spec.md documents the feature requirements, constraints, non-goals, and acceptance criteria.
  • plan.md outlines the proposed implementation approach.
  • verification.md records how the implementation is validated against the acceptance criteria.

We recommend keeping feature specifications separate from CLAUDE.md. Large instruction files can consume valuable context and become harder to maintain as the project grows. Instead, keep CLAUDE.md focused on repository-wide engineering rules and instruct Claude Code to read the relevant feature specification before starting a task.

How to Implement Spec-Driven Development with Claude Code

The loop has six steps. We have shown a late-fee feature throughout since billing logic contains enough edge cases to make weak specs visible.

Spec-Driven Development with Claude Code process

Step 1: Define and Document the Specification

The specs have four sections:

  • Outcome
  • Constraints
  • Non-goals
  • Acceptance criteria.

Based on our experience, we keep feature specifications concise and focused on the requirements that need to be implemented and verified. Longer specifications can make reviews harder, particularly when they include implementation details that belong in the development plan

Late fees on overdue invoices

Outcome
An invoice that is unpaid after its due date plus the grace period
accrues one late fee, calculated on the unpaid balance.

Constraints
– Grace period is 5 calendar days, evaluated in the customer’s billing time zone.
– Fee is 1.5% of the unpaid balance, rounded half-up to the cent.
– Reuse the existing Money type. No floating point arithmetic.

Non-goals
– No changes to the database schema or existing migrations.
– No changes to the invoice PDF renderer.
– No recurring monthly fees. One fee per invoice.

Acceptance criteria

– Due 1 June, unpaid at 6 June 23:59 customer time: no fee.

– Same invoice at 7 June 00:00 customer time: one fee applied.

– Invoice 40% paid: fee is calculated on the remaining 60%.

– Running the job twice on the same day creates one fee record.

– Existing tests in billing/ pass unmodified.

In our experience, non-goals are among the most important parts of a specification because they make the boundaries of the requested change explicit and help prevent unnecessary modifications.

Step 2: Explore the Repository and Plan

In spec-driven development using Claude Code, Claude can help teams create the spec itself. Switch to plan mode (Shift+Tab cycles through the permission modes) and ask Claude to interrogate the spec:

Read specs/late-fees/spec.md and explore the billing/ directory.

 

Identify existing functions, services, and data models that can be reused.

List any ambiguities, missing requirements, and assumptions that could

affect implementation.

 

Ask me questions about unresolved requirements before finalizing the plan.

 

Once the requirements are clear, create

specs/late-fees/plan.md.

 

Do not modify source files or existing tests.

Claude may identify several unanswered questions during this exercise. In our case, one question was whether the grace period should exclude weekends, an edge case we had not initially considered. Once we clarified the requirement, the decision was added to the specification and reflected in the implementation plan.

Step 3: Break the Plan into Verifiable Tasks

Upon asking, Claude will create a checklist from the approved plan and verify all the components itself.

– [ ] T1: Add failing tests for acceptance criteria 1–4.
– [ ] T2: Implement fee calculation in billing/lateFee.ts.
– [ ] T3: Integrate the scheduled job with an idempotency mechanism.
– [ ] T4: Run the billing test suite and report results.

Since the task list is maintained in the repository, progress can continue across sessions. When a session ends or its context is cleared, start a new session by asking Claude Code to read the specification, implementation plan, and task list. It can then identify the completed tasks and resume from the next unchecked item

Step 4: Implement Incrementally

Per one session segment, run one task, followed by a commit. Remember to clear the context between tasks because long sessions collect past assumptions, and those start to override the current spec.

Read spec.md, plan.md and tasks.md. Implement T2 only.
Stop when its tests pass and tick the box.

With the tests coming first (T1), Claude has a concrete failing goal, and you can confirm the spec has been changed into runnable form before it starts coding the feature.

Step 5: Verify Against the Specification

A subagent takes the lead in this part of Claude Code spec-driven development. Run one that can only see the diff and the spec, nothing of the implementation of the conversation (to remove the author’s bias). Ask Claude Code to report each criterion as met, unmet or unverifiable, and to attach any evidence like test output.

Step 6: Update the Spec and Document

Update the specification whenever approved requirements change, and keep it aligned with the implemented behavior. The specification and corresponding code changes should be reviewed together in the same pull request. Completed implementation tasks and historical change records can be archived, but the current specification should remain accessible as a reference for future development and maintenance

How to Make Spec-Driven Development Repeatable with Claude Code

  • md holds the standing rules. Keep the section short as Anthropic also recommends concise files. Long ones dilute the important instructions.

Spec workflow
– Every feature has specs/<name>/spec.md, plan.md and tasks.md.
– Read the spec before editing code. If the request and the spec disagree, stop and ask.
– Do not edit a spec’s non-goals without approval.
– Existing tests are read-only unless the current task says otherwise.

  • A skill standardizes the drafting process of specs. Save this as .claude/skills/spec-new/SKILL.md.

name: spec-new
description: Create a feature spec from the team template. Use when starting a new feature.
—
Create specs/$ARGUMENTS/spec.md from specs/_template.md. Ask up to eight
questions about missing outcomes, constraints and non-goals before writing.
Do not propose an implementation.

  • A hook comes with that one rule our team does not leave to chance. Claude used to do test masking before where it would edit an existing code so that its code could pass the test. Hook blocks edits to existing test files and tells Claude what to do instead.

Register it under PreToolUse in .claude/settings.json with a matcher of Edit|Write|MultiEdit.

#!/usr/bin/env bash
# .claude/hooks/protect-tests.sh
file=$(jq -r ‘.tool_input.file_path // empty’)
if [[ “$file” == *.test.ts && -f “$file” ]]; then
echo “Existing tests are locked. Record the reason in tasks.md and ask for approval.” >&2
exit 2
fi
exit 0

An exit code of 2 blocks the action and returns the message to Claude. It then creates a path forward to avoid a dead end.

  • A reviewer subagent lives at .claude/agents/spec-reviewer.md.

name: spec-reviewer
description: Checks a diff against the acceptance criteria of a feature spec. Use after implementation.
tools: Read, Grep, Glob, Bash
—
Compare the diff with specs/<feature>/spec.md. For each acceptance criterion
report met, unmet or unverifiable, citing a test name or command output.
List every changed file the plan did not mention. Never edit files.

Claude Code vs. GitHub Spec Kit vs. OpenSpec vs. Kiro vs. BMAD for SDD

GitHub Spec Kit, OpenSpec, and BMAD can work on top coding agents, Claude Code among them, and Kiro provides its own development environment and spec workflows.

Tool What it is Best fit Process overhead
Native Claude Code A workflow assembled from built-in capabilities Individuals and small teams that want control Low, you design it
GitHub Spec Kit Open-source, agent-agnostic toolkit Teams standardizing several agents Medium
OpenSpec Specification-driven framework supporting AI coding assistants Changes to existing codebases that need a lightweight record Low to medium
Kiro An agentic IDE with spec-driven workflow built in Teams planning to use a new editor Medium
BMAD A methodology with specialized roles and workflows Larger efforts that map to well-set team roles High

A Practical Example of Spec-Driven Development with Claude Code

We ran the late-fee feature twice, once with the one-sentence prompt and once using the six-step loop. The second showed the value of this.

The spec our developer wrote

The spec is the one shown in Step 1. It took about twenty minutes to write, which was longer than expected for a feature they believed they understood.

What Claude got wrong, and what the spec caught

Three problems appeared and were caught at a different gate.

  • During planning, Claude proposed a new late_fee_applied_at column on the invoice table.
  • During implementation of T2, Claude tried to edit an existing rounding test that expected half-even behavior.
  • During review, the subagent marked criterion 4 as unverifiable because no test ran the job twice.

Time, token and rework vs a prompt-only attempt

Measure

Prompt-only

Spec-driven

Time to merge-ready 6.5 Hours 5 Hours
Tokens used 48,000 62,000
Review rounds 3 1
Files changed outside scope 3 0
Rework Effort 2 Hours 30 Minutes

The pattern we expect, and observed in qualitative terms, is that the spec-driven workflow with Claude Code run spends more tokens and time before the first line of code and less during review. Whether the total comes out ahead depends on feature size.

Case Study: Writing the Spec Before the Code for a Chemical Marketplace

Our AI team worked with a venture-backed B2B chemical marketplace. The project was converting a business largely dependent on brokers and phone calls into a digital platform. The system needed new features like supplier verification, chemical specifications, price negotiations, transactions, etc.

Here’s how we did it:

  • The spec came first: Claude drafted it, our experts reviewed it. Business rules were traced to the tests that prove it.
  • Prioritize flagging: When the AI met ambiguity, it paused and raised a question instead of taking a product decision.
  • Open questions stayed visible: Each of the 423 open questions had its own ID and closed only with a recorded decision.
  • Every rule was labeled: For no assumption to stay hidden, rules were tagged Confirmed, Provisional or Open Question.
  • Several tools, each with one job: Claude wrote the specs, ChatGPT handled research and cross-checking, and GitHub Spec Kit moved the work from spec to code.

 

Following this approach, we could deliver a build-ready blueprint with 126 use cases. The client could agree on scope and an MVP with evidence, and the platform is now being built.

Common Spec-Driven Development Mistakes and When to Avoid It

  • Over-specifying implementation is the first mistake. A spec that dictates function names and file layout does not give Claude any room to find the existing helper that already does the job. It recreates the weaknesses of a long design document.
  • Letting specs drift comes second. A spec that disagrees with the code teaches the agent and the team to ignore specs altogether.
  • Treating CLAUDE.md as enforcement is the third. Because it is advisory, a rule that matters needs a hook or a test.
  • Context bloat follows from loading every spec, every skill and a long CLAUDE.md into each session, which pushes out the material the current task needs.
  • Reviewing generated specs carelessly is the quietest failure. When Claude drafts the spec and you approve it without reading, the document records the agent’s guesses and gives them an air of authority.

For tiny changes, our rule of thumb is that a change fitting in one file with no behavior a user could notice does not need a spec. A typo fix or a log message gets a normal prompt. A change with two or more acceptance criteria, any data model impact, permissions or personal data gets the full loop.

Getting Started with Spec-Driven Development in Claude Code: One-Hour Setup Checklist

  1. Run /init and trim the generated CLAUDE.md to the short workflow section shown above (10 minutes).
  2. Create specs/_template.md with the four sections: outcome, constraints, non-goals, acceptance criteria (10 minutes).
  3. Add the spec-new skill and the spec-reviewer subagent (10 minutes).
  4. Add the test-protection hook and confirm it blocks an edit by trying one (10 minutes).
  5. Pick a real feature of moderate size and run it through the six steps, recording time, tokens and review rounds (20 minutes to start, the remainder as the feature requires).

Working with Rishabh Software on Spec-Driven Development with Claude Code

SDD with Claude Code is useful when expected behavior and technical constraints need to be clearly defined, especially when software changes can affect authorization, financial calculations, integration contracts, or other existing system behaviors that developers need to preserve.

Claude Code offers features that support a practical workflow for specification, planning, implementation, and verification.

However, responsibility for the decisions remains with the engineering team. Someone must determine whether the requirements are complete, whether the proposed implementation fits the existing system, and whether the changes meet the intended business and technical requirements. A well-maintained specification makes these decisions easier to communicate and review, but it cannot make them on behalf of the team.

Bridging the gap between a business requirement and a technical specification is an important part of our work as an AI development company. Our SDD approach combines AI-assisted specification drafting with reviews by experienced engineers and analysts, who validate requirements and technical decisions before implementation begins.

Organizations typically approach us in one of these three scenarios:

  • Before a build: To translate business goals into clear, actionable technical specifications.
  • During a build: To establish or improve a spec-driven development workflow with Claude Code.
  • On an existing product: To document current system behavior and ensure new changes do not disrupt established processes.

Introducing SpecCraft: Rishabh Software’s Open-Source SDD Framework

To make spec-driven development more structured and repeatable, Rishabh Software has developed SpecCraft, an in-house framework released as an open-source tool. It helps teams establish a stage-gated SDD workflow, moving from business requirements and technical design to task decomposition, implementation, testing, and validation.

SpecCraft is designed to work with AI coding assistants such as Claude Code, Gemini CLI, and GitHub Copilot. Teams can use it with their existing agent tooling, adapt the generated workflow to their project requirements, and retain control over the resulting files without depending on a proprietary framework or a continuing SpecCraft runtime.

The framework is available as an NPM package and through a public GitHub repository, allowing engineering teams to explore and adopt it. We also conducted an internal hackathon around SpecCraft, receiving positive feedback from participants on its approach to structuring AI-assisted development.

By making SpecCraft open source, we aim to give engineering teams a practical starting point for adopting SDD while allowing them to customize the workflow to suit their technology stack, development practices, and project needs.

Frequently Asked Questions

Q: Can I use GitHub Spec Kit with Claude Code?

A: GitHub Spec Kit works with Claude Code, since the toolkit is built to run with multiple coding agents. After it is initialized in a repository, it supplies templates and commands for specifications, plans and task lists that Claude Code then follows.

Q: Does spec-driven development reduce AI coding errors?

A: It lowers the number of errors that stem from misread or missing requirements, such as wrong assumptions like unrequested changes and skipped constraints. Logic mistakes inside correct requirements remain possible, which is why acceptance criteria written as tests and a separate review step belong in the workflow.

Q: How can I prevent Claude Code from ignoring requirements?

A: Create a short spec with testable acceptance criteria that Claude reads at the start of each task. Clearing the context between tasks keeps earlier assumptions from overriding the document. Any rule that must hold every time belongs in a hook.

Q: Is spec-driven development suitable for existing applications?

A: Existing applications are a good fit, given that the spec begins with a description of current behavior. A subagent can explore the relevant code and record how it behaves today, and the new requirements are then written against that baseline. This protects undocumented behavior from being altered while the new feature is added.

Q: How do I verify that Claude Code followed a specification?

A: Convert each acceptance criterion into a test that can be run. A reviewer subagent then compares the diff with the spec and marks every criterion as met, unmet or unverifiable with evidence. A criterion without evidence counts as unmet, and a final check makes sure change files align with the approved plan.

Q: How long should a spec be, and what goes in it?

A: A spec for a single feature generally runs between forty and eighty lines, which keeps it readable for a reviewer and light enough to load into context. It should contain the outcome, the constraints, the non-goals and the acceptance criteria. Implementation details such as function names and file layouts are better left to the plan.

Trending Topics

Need Help Implementing Spec-Driven Development with Claude Code?