Blog
5 min read

Spec-Driven Development With Claude Code: Write the Spec, Then Let the Agent Build

Spec-driven development means agreeing on a written specification before an AI agent writes code. What a good spec contains, a practical workflow with Claude Code (spec → plan → tasks → implement → verify), templates, and when it's overkill.

"Vibe coding" — describing what you want and iterating on whatever comes back — is fast for small things and chaotic for big ones. Spec-driven development is the opposite habit: before the agent writes code, you and the agent agree on a written specification of what will be built and how you'll know it's done. The spec, not the chat history, becomes the source of truth.

It's become a popular way to work with Claude Code and other agents, and several open-source toolkits package the approach. You don't need any special tool to start.

Why it works with agents

Agents are good at following clear instructions and bad at reading your mind. A spec helps because:

  • It forces decisions early. Ambiguities ("what happens if the email is already taken?") get answered before code exists, not discovered in review.
  • It survives context loss. Conversations get compacted or cleared; a file on disk doesn't. (/compact vs /clear.)
  • It's reviewable. Reading a one-page spec is far faster than reviewing 1,500 lines of generated code to find out what it does.
  • It defines "done". Acceptance criteria turn into tests the agent can run itself.
  • It enables parallelism. Independent tasks from one spec can go to separate agents. (Parallel agents with git worktrees.)

What a good spec contains

Keep it short — one to three pages for a feature. A template:

# Spec: Team invitations

## Problem
Account owners can't add teammates; they share passwords instead.

## Goals
- Owners can invite people by email to their team.
- Invitees join with their own account.

## Non-goals
- Role customisation (owner/member only for now).
- SSO.

## User flows
1. Owner opens Settings → Team, enters an email, clicks Invite.
2. Invitee receives an email with a link valid for 7 days.
3. Invitee signs up or logs in, and lands in the team.

## Requirements and rules
- Only owners can invite or remove members.
- Inviting an existing member shows "already a member".
- Max 20 members per team on all plans.
- Invite links are single-use.

## Data
- New table `team_invitations(id, team_id, email, token_hash, expires_at, accepted_at)`.

## Acceptance criteria
- [ ] A member (non-owner) gets 403 when calling the invite API.
- [ ] An expired link shows "This invitation has expired".
- [ ] Accepting twice doesn't create two memberships.
- [ ] Removing a member revokes their access immediately.

## Open questions
- Should pending invitations count toward the 20-member limit? → Yes.

The non-goals and acceptance criteria sections do the most work. Non-goals stop the agent gold-plating; acceptance criteria tell it when to stop.

A workflow with Claude Code

1. Draft the spec together

In plan mode, describe the feature and ask Claude to interview you:

I want to add team invitations. Before writing any code, ask me questions until you understand the requirements, then write a spec to docs/specs/team-invitations.md using the template in docs/specs/TEMPLATE.md.

Answer its questions. Edit the spec yourself — it's your document.

2. Turn the spec into a plan

Read the spec. Propose an implementation plan: files to change, schema migration, API routes, UI, and tests. Note risks. Don't write code yet.

Review the plan for things that conflict with how your codebase works.

3. Break it into tasks

Break the plan into small, independently testable tasks in docs/specs/team-invitations-tasks.md, each with a checkbox.

Small tasks are easier for the agent to get right and for you to review.

4. Implement task by task

Implement task 1. Write the tests from the acceptance criteria first, then make them pass. Tick the task when done and commit.

Between tasks, /clear freely — the spec and task list carry everything forward.

5. Verify against the spec

Check the implementation against every acceptance criterion in the spec. Run the tests. List anything not met.

Then do your own review. (How to review a pull request written by an AI agent.)

Make it a habit with project files

  • Put the template in docs/specs/TEMPLATE.md.
  • Add a line to CLAUDE.md: "For any feature larger than a small fix, write or update a spec in docs/specs/ before implementing." (How to write a CLAUDE.md.)
  • Turn the workflow into a skill or slash command so the steps are one command away.
  • Keep specs updated when requirements change — a stale spec misleads the next agent.

When it's overkill

Not everything needs a spec. Skip it for:

  • small bug fixes with a clear cause,
  • copy and styling tweaks,
  • throwaway prototypes where you're exploring what you even want.

A useful threshold: if the change touches the database schema, permissions, payments, or more than a couple of files, write the spec.

The summary

  • Spec-driven development: agree on a written spec before the agent codes.
  • A good spec has goals, non-goals, flows, rules, data, acceptance criteria and open questions.
  • Workflow: spec → plan → tasks → implement with tests → verify against the spec.
  • Keep specs in the repo so they outlive any conversation.

EasySpawn runs Claude Code on a persistent server where specs, task lists and code live together on disk — and the agent can run your app and tests to verify every acceptance criterion. See how it works or join the waitlist.

Related: How to Plan Your First App · Getting AI to Write Tests That Actually Catch Bugs · Context Engineering for Coding Agents · How to Write Good Prompts for AI Coding Tools

Keep reading