Spec-Driven Development With Claude Code: A Practical Guide

Claude Code can write code quickly, but speed is not the same as building the right thing. When you give it a vague prompt such as “add photo sharing” or “build an export feature,” it has to guess many unstated requirements: file formats, permissions, edge cases, architecture, validation rules, and what should be excluded.

Spec-driven development (SDD) solves that problem by making the specification the source of truth before implementation begins. You define what the software should do, what it should not do, and how success will be verified. Claude Code then explores the repository, creates a plan, implements the change, and validates the result against the spec.

What Is Spec-Driven Development?

Spec-driven development is a workflow built around three documents:

1. Spec — what the change should do and what it should not do.

2. Plan — the ordered implementation steps.

3. Code — the implementation written against the plan.

A human review sits between each phase:

• Review the spec before it becomes a plan.

• Review the plan before code is written.

• Review the code before it is merged.

The specification is not just a prompt. It is a durable file that survives across sessions, can be reviewed by teammates, and gives Claude a clear definition of success.sam-solutions

Why Vibe Coding Breaks Down

“Vibe coding” works well for prototypes, single-file changes, and throwaway scripts. It becomes risky when a feature touches multiple files, affects real users, or requires architectural consistency.

Ambiguous requirements

A prompt such as:

“Allow administrators to export customer records.”

does not define:

• Which administrator roles are allowed.

• Which fields can be exported.

• Whether exports need audit logging.

• How large datasets are handled.

• Whether files should expire.

• What format should be used.

Claude may build a simple synchronous CSV download for every administrator. The business may have expected an encrypted, asynchronous export restricted to compliance officers and deleted after 24 hours.

Both implementations match the prompt. Only one matches the real requirement.

Architectural drift

Each AI-generated change may look reasonable on its own, but together they can violate the system’s intended design.

For example, one session may add refund notifications directly to a payment controller. Another may place similar logic in the order service. A third may introduce a separate queue for bulk refunds.

Each feature may pass its own tests, but the codebase now has three notification paths with different retry rules, observability, and failure handling.

Inconsistent implementation

Without shared conventions, Claude may produce different error formats, naming patterns, validation styles, logging approaches, or testing depths across features.

One endpoint might return:

json

{ "message": "Not found" }

Another might return:

json

{ "error": { "code": 404 } }

A third might return plain text.

The problem is not necessarily any single endpoint. The problem is the absence of a shared implementation contract.

Spec-Driven Development vs. Plan Mode

Claude Code’s Plan Mode is useful, but it is not the same as full spec-driven development.

Feature	Plan Mode	Spec-Driven Development
Persistence	Lives in a single chat turn	Saved as files on disk
Survives /clear or restart	No	Yes
Review checkpoints	One: approve the plan	Two or three: spec, plan, code
Team visibility	Limited to terminal history	Anyone with repository access can review
Best for	Contained changes	Multi-file features, refactors, cross-session work

Plan Mode helps Claude explore a repository and propose changes without editing files. SDD adds durable requirements, review gates, traceability, and validation against an agreed source of truth.sam-solutions+1

What a Good Spec Contains

A strong specification gives Claude enough information to build the right solution without inventing product decisions.

1. Business goal

Explain why the feature exists.

Instead of:

“Build a customer data export.”

Write:

“Reduce manual support requests by allowing account owners to export their own data without staff assistance.”

2. User scenario

Describe who uses the feature and how.

Example:

“An authenticated account owner requests an export from the privacy settings page, receives a notification when it is ready, and downloads it within 24 hours.”

3. Functional requirements

Define observable behaviour:

• Authorised roles.

• Included records.

• Supported formats.

• Request limits.

• Job statuses.

• Notification behaviour.

• Download expiry.

• Audit events.

Use testable language:

“The system must reject a second export request while another request is processing.”

That is clearer than:

“The system should prevent unnecessary exports.”

4. Technical constraints

Tell Claude which solution space is acceptable.

For example:

• Use the existing worker queue.

• Store encrypted files in the approved object-storage service.

• Preserve current public API contracts.

• Do not introduce another third-party dependency.

5. Edge cases

Cover conditions outside the ideal workflow:

• Large accounts.

• Duplicate requests.

• Deleted records.

• Revoked permissions.

• Interrupted jobs.

• Unavailable storage.

• Expired download links.

6. Acceptance criteria

Convert the spec into a pass-or-fail contract.

Examples:

• A user whose access is revoked before completion must not receive a valid download link.

• A failed job must produce an audit event without exposing partial data.

• The system must return HTTP 429 with a Retry-After header when the rate limit is exceeded.

How CLAUDE.md Supports SDD

CLAUDE.md is the persistent steering layer for Claude Code. It loads repository-specific instructions at the start of every session.

Use it for:

• Coding standards.

• Naming rules.

• Repository architecture.

• Build commands.

• Test commands.

• Linting commands.

• Hard constraints.

Example:

text

# Project Guide ## Stack - Next.js - TypeScript - PostgreSQL - Prisma - Vitest ## Commands - Build: `npm run build` - Test: `npm test` - Lint: `npm run lint` ## Rules - Use server components by default. - Do not use `any`. - Do not write raw SQL. - Every API endpoint must have tests. - Do not modify database migrations without approval.

Keep CLAUDE.md concise—ideally under 200 lines. Move detailed, occasionally needed instructions into lazy-loaded rules or skills. A bloated instruction file can dilute model attention and reduce adherence during long sessions.

The Six-Step SDD Workflow

Step 1: Explore the repository

Claude Code should inspect the repository before editing anything.

It should identify:

• Relevant modules.

• Dependencies.

• Interfaces.

• Data models.

• Tests.

• Architectural patterns.

• Existing conventions.

Step 2: Clarify requirements

Resolve ambiguity before writing the spec.

Ask questions about:

• Users.

• Business outcomes.

• Permissions.

• Workflows.

• Data ownership.

• Failure behaviour.

• Exclusions.

• Measurable success.

Step 3: Create the specification

Turn the clarified requirements into a reviewable contract.

Include:

• Business goals.

• User scenarios.

• Functional requirements.

• Technical constraints.

• Edge cases.

• Acceptance criteria.

• Out-of-scope work.

Step 4: Generate the technical plan

Claude Code should convert the approved spec into an ordered implementation plan.

The plan should name:

• Files to modify.

• Interfaces to change.

• Data flows.

• Migrations.

• Dependencies.

• Tests.

• End-to-end verification steps.

Step 5: Implement and test

Claude Code should implement the plan in small, testable increments.

Run:

• Unit tests.

• Integration tests.

• Contract tests.

• Security tests.

• End-to-end tests.

Choose the test types based on the feature’s risk profile.

Step 6: Review the final diff

Compare the complete diff with the spec and plan.

A human reviewer—or a fresh-context Claude Code reviewer—should check:

• Every requirement is implemented.

• Edge cases have tests.

• Architectural boundaries remain intact.

• No unrelated changes entered the scope.

Example: Building a Data Export Feature

Instead of saying:

“Build a customer data export feature.”

Start with a spec:

text

# Customer Data Export ## Goal Allow authenticated account owners to export their own data without contacting support. ## User Scenario An account owner requests an export from the privacy settings page. They receive a notification when the export is ready and can download the file within 24 hours. ## Functional Requirements - Only account owners can request an export. - Exports include profile, orders, and preferences. - Supported format: CSV. - Only one export can run at a time per account. - The user receives an email notification when the export is ready. - Download links expire after 24 hours. - Every export request is recorded in the audit log. ## Technical Constraints - Use the existing background worker queue. - Store files in the approved encrypted object-storage service. - Do not change existing public API contracts. - Do not add new third-party dependencies. ## Edge Cases - Large accounts with more than 100,000 records. - Duplicate export requests. - Deleted records. - Revoked permissions. - Interrupted jobs. - Expired download links. ## Acceptance Criteria - A revoked user must not receive a valid download link. - A failed job must create an audit event. - A second export request must be rejected while one is processing. - A completed export must expire after 24 hours.

Then ask Claude Code:

text

Read spec.md and create an implementation plan. Do not write code yet.

After approving the plan:

text

Implement task 1 from plan.md. Write the required test first. Run the test suite. Fix failures before moving to task 2.

How Tests, Hooks, and Agents Enforce the Spec

A written specification becomes stronger when it is backed by executable checks.

Requirements-to-test mapping

Each test should reference a specific requirement or acceptance criterion. This makes it easier to detect unimplemented requirements.

Automated validation

Hooks can run tests, linters, type checks, security scanners, or policy scripts automatically. Unlike CLAUDE.md, which guides model behaviour, hooks execute deterministic controls and can block progress when a check fails.

Task decomposition

Agents can divide an approved plan into bounded tasks with clear inputs, outputs, dependencies, and acceptance criteria.

For example:

• One agent implements a database migration.

• Another prepares API contract tests.

• A third reviews the final diff.

Independent verification

A separate reviewer should compare the final diff with the spec without inheriting the implementer’s reasoning.

The reviewer should look for:

• Missing requirements.

• Untested edge cases.

• Architectural violations.

• Unrelated changes.

Human approval should remain the final gate for important business, security, and release decisions.

Frameworks That Extend the Workflow

You do not need a framework to use SDD. A simple spec.md, plan.md, and disciplined workflow is enough. But several tools can add structure.

Framework	Primary focus	Best for
Superpowers	TDD and subagent auditing	Solo developers and small teams
GitHub Spec Kit	Governance and artifact standards	Multi-developer teams and enterprise repositories
BMAD Method	Agile workflows and persona agents	Large codebases and end-to-end epics

Superpowers

Superpowers is a plugin-based skills framework that enforces development discipline inside Claude Code. It supports brainstorming, spec creation, planning, test-driven development, and subagent-based code review.

Install it with:

bash

/plugin install superpowers@claude-plugins-official

GitHub Spec Kit

GitHub Spec Kit provides an artifact-driven workflow built around a project constitution, feature specification, technical plan, task list, implementation, and convergence review.

Its commands separate what and why to build from technology and architecture decisions.

BMAD Method

BMAD Method uses role-oriented agents for product, architecture, UX, development, and testing. It is better suited to larger projects that need formal planning and role separation.sam-solutions+1

Benefits of Spec-Driven Development

• Predictability: Claude and reviewers share the same definition of success.

• Traceability: Requirements can be traced through plans, code, and tests.

• Fewer wrong assumptions: Ambiguity is resolved before implementation.

• Better architecture: The spec prevents gradual architectural drift.

• Faster reviews: Reviewers compare the diff against explicit requirements instead of reconstructing intent.

• Better collaboration: Specs can be reviewed by product managers, designers, architects, and engineers.

• Cross-session continuity: Work can continue cleanly in a new session because decisions are stored in files.

Limitations to Understand

SDD is not free.

• Specs take time to write.

• Specs can become outdated.

• Long sessions can still exhaust useful context.

• Too much process slows down simple changes.

• A spec improves consistency but does not guarantee correctness.

• Tests and human review are still required.

Use a full specification for multi-file features, refactors, authentication, payments, migrations, and business-critical workflows. Do not use it for a typo fix, a rename, or a one-line CSS change.

How to Adopt SDD

Start with a pilot project.

1. Choose one meaningful feature.

2. Write a simple spec.

3. Ask Claude to create a plan.

4. Review and edit the plan.

5. Implement one task at a time.

6. Require tests for each task.

7. Review the final diff against the spec.

8. Update the spec whenever behaviour changes.

Create shared templates for:

• Specifications.

• Technical plans.

• Task lists.

• Review checklists.

Establish clear ownership:

• Product owners approve business behaviour.

• Architects own system boundaries.

• Security specialists review sensitive workflows.

• Engineering leads authorise implementation.

Measure whether the workflow improves delivery quality before scaling it across the team.

Key Takeaways

• Spec-driven development turns informal prompts into controlled engineering workflows.

• The spec defines what to build; the plan defines how to build it; code implements the plan.

• Human review should happen at the spec, plan, and final-code stages.

• CLAUDE.md provides persistent project context, while specs define individual features.

• Tests, hooks, and independent reviewers turn specifications into enforceable checks.

• SDD is most valuable for complex, multi-file, high-risk, or cross-session work.

• Do not over-apply it to trivial changes.

Final Takeaway

Spec-driven development changes the relationship between you and Claude Code.

Instead of treating the prompt as the source of truth, the specification becomes the source of truth. Claude Code becomes an implementation engine that follows your requirements, respects your constraints, and proves its work through tests.

The practical formula is:

text

Clear spec + approved plan + small implementation steps + automated tests + final diff review

Use that formula for anything more complex than a quick one-file change, and Claude Code becomes far more predictable, maintainable, and safe to use in real projects.