Spec-driven development with Claude Code: a step-by-step example
A small feature, from idea to code with Spec Kit and Claude Code: spec, plan, tasks, implementation and what to do if the agent drifts.
Spec-driven development with Claude Code means writing down what the feature must do first, letting the agent ask you about whatever you left ambiguous, and only then planning, breaking the work into tasks and coding. This tutorial walks through the process with GitHub Spec Kit and a small example: tags in a to-do list.
You need to know what a git repository is and to have asked an assistant to write you a function at least once. The full definition is in what is spec-driven development and the tool comparison is in OpenSpec vs Spec Kit vs BMAD; we won’t repeat them here.
A word of honesty: the commands, files and folders are the real ones, checked by reading the documentation and templates in the official repository[1], but we have not run them. The feature, the spec, the plan and the tasks are an illustrative scenario built from those templates; the text your agent generates will be different, although the shape of the process repeats.
Spec Kit tutorial with Claude Code: from idea to code
First, set up the project.
Spec Kit is a CLI (specify) plus a set of commands that, after specify init, become available in your coding agent. An agent, like Claude Code, is a program that reads your files and writes changes on its own; from here on, “the agent”.
You need Python 3.11 or higher and uv, a Python tool installer[1]:
uv tool install specify-cli
specify init mis-tareas --integration claude
cd mis-tareas
claude
The --integration claude option installs the commands as Claude Code skills, in .claude/skills/speckit-<comando>/SKILL.md[2]. A skill is an instruction file that the agent loads when you invoke it. The documentation writes the commands with a dot (/speckit.specify), but in Claude Code they are invoked with a hyphen, /speckit-specify[2][3].
These commands are typed in the Claude Code chat, not in the terminal, and you run them one at a time, reviewing the result before moving on to the next[9]. That pause is what lets you correct things before the agent piles up decisions on your behalf.
The constitution: rules that apply to every feature
You run it once per project and it sets the principles that everything else is evaluated against:
/speckit-constitution Simple, readable code. Every new behavior comes with a test. No new dependencies if the standard library is enough.
The result is saved in .specify/memory/constitution.md[4]. Whatever you put here applies to all future features, so keep it short.
The spec and the question you hadn’t thought of
Now the feature, in natural language, focused on the what and without technology[3]:
/speckit-specify I want to be able to tag tasks ("home", "work") and filter the list by tag.
Spec Kit creates a numbered folder inside specs/ and writes spec.md there[5], with prioritized user stories, Given/When/Then scenarios and numbered requirements (FR-001…)[6]. An illustrative excerpt:
### User Story 1 - Tag a task (Priority: P1)
**Acceptance Scenarios**:
1. **Given** a task with no tags, **When** I add "home",
**Then** the task shows the tag "home".
2. **Given** a task with the tag "home", **When** I add "Home",
**Then** [NEEDS CLARIFICATION: is it the same tag or a different one?]
- **FR-003**: The user MUST be able to filter the list by a tag.
- **FR-004**: [NEEDS CLARIFICATION: with two tags selected,
are tasks shown that have both or either of them?]
Look at the second scenario: you hadn’t thought about capital letters. If you ask for the code directly, the agent decides on its own, and most likely it will compare strings as they are: “Home” and “home” would be two tags and the filter would have odd duplicates that you would only discover once the app is in use.
Here it can’t decide silently: the command template marks as [NEEDS CLARIFICATION] the decisions that change the scope or the experience, with a maximum of three markers, and asks you for the answers before going on[5]. That is the moment that justifies the method: answering a question now costs almost nothing, and discovering the same decision once the code is written forces you to redo it.
You answer: the same tag regardless of capitalization or spaces, and the multiple filter shows the tasks that have all of them. The criteria become verifiable:
- **FR-002**: "Home", "home" and " home " MUST be the same tag;
it is displayed with the spelling used when it was first created.
- **FR-004**: Filtering by several tags MUST show only the tasks
that have all the selected ones.
If you want to refine further, /speckit-clarify asks up to five questions about whatever is still loose and writes the answers into spec.md[3]. Before moving on, read the whole spec carefully: fixing it now is much cheaper than fixing the plan, tasks and code that hang from it.
The plan: this is where technology comes in
With the spec closed, you decide the how; here, and only here, you name the stack[3]:
/speckit-plan The app is TypeScript with React and stores data in localStorage. Tests with Vitest.
It generates plan.md in the same folder, with a technical context (language, dependencies, storage, testing) and a check against the constitution[7]. Review it with one concrete question: does it contradict anything in the spec? For example, a plan that stores tags as an unnormalized string[] would clash head-on with FR-002.
The template also provides auxiliary files (research.md, data-model.md, contracts/…); in a feature this small it is normal for several of them to be unnecessary.
The tasks and the last review before coding
/speckit-tasks
It generates tasks.md, ordered by dependencies, with an identifier and the file path on each task[8]:
- [ ] T001 Create Tag type and normalizeTag function in src/lib/tags.ts
- [ ] T002 [P] [US1] Test: "Home" and " home " are the same tag in src/lib/tags.test.ts
- [ ] T003 [US1] Add tags to the task in src/lib/tasks.ts
- [ ] T004 [US1] Filter by several tags with "all" semantics in src/lib/filter.ts
[P] marks a task that can run in parallel[8]. Notice that T002 comes straight out of the ambiguous scenario: the question you answered is already a test.
Before implementing there is one optional gate left, /speckit-analyze: read-only, it cross-checks spec, plan and tasks and points out conflicts and gaps[3]. If it finds something, fix it in the step that caused it and regenerate whatever hangs from it.
Implement, converge and what to do when the agent drifts
/speckit-implement
It runs the tasks in dependency order[3]. Your role is to check that the output meets the acceptance scenarios: run the tests and try “Home” against “home” by hand.
Suppose the agent normalizes when saving but not when filtering, and filtering by “home” doesn’t find the tasks saved as “Home”. It happens to us that the first reaction is to ask in the chat “fix the filter” and move on, but that way the fix only lives in that conversation. It is better to look at where the failure is:
- If the spec already said the right thing (here it did:
FR-002), the failure is in the implementation. Point to the requirement and check thatT002or a new test covers it. - If the spec didn’t say it, the failure is yours and it gets fixed first in
spec.md, then in the plan or the tasks if they change, and only then do you implement again.
To find out whether anything is left uncovered there is /speckit-converge, which compares the code against the spec, the plan and the tasks and can only add new tasks to tasks.md. If there are no gaps it answers Converged; if there are, you run /speckit-implement again and repeat until it converges[3].
| Command | What it writes | When you use it |
|---|---|---|
/speckit-constitution | .specify/memory/constitution.md | Once per project |
/speckit-specify | spec.md in the feature folder | At the start of each feature |
/speckit-clarify | Answers inside spec.md | Optional, if the spec is still loose |
/speckit-plan | plan.md (and auxiliary files) | When the spec is closed |
/speckit-tasks | tasks.md | When the plan convinces you |
/speckit-analyze | Nothing (report only) | Before implementing, if there is risk |
/speckit-implement | The code for the tasks | After reviewing spec, plan and tasks |
/speckit-converge | New tasks in tasks.md | After implementing, until Converged |
When spec-driven development doesn’t pay off
To fix a typo, rename a variable or build a prototype you’re going to throw away, the spec costs more than the change: you just ask for it directly and review it in the diff.
A useful rule: if you can’t imagine an ambiguous question the agent would have to answer for you, you don’t need a spec. The tags needed one because they hid product decisions (capitalization and combined filtering, for a start) that nobody had made yet. And if the whole process feels like too much ceremony, there is the short version: specify, plan, tasks, implement and converge, without the optional gates[9]. The full one, for anything headed to production.
Sources
- Spec Kit: official README, GitHub: requirements and installation with
uv. - Spec Kit: Claude Code, official documentation:
--integration claudeand the skills path. - Spec Kit: Agentic SDD reference, GitHub: what each command does.
- Spec Kit: constitution command template, GitHub: constitution path.
- Spec Kit: specify command template, GitHub:
specs/folder and the three-marker limit. - Spec Kit: spec template, GitHub: stories, scenarios and
FR-###requirements. - Spec Kit: plan template, GitHub: technical context and auxiliary files.
- Spec Kit: tasks template, GitHub: identifiers and the
[P]marker. - Spec Kit: SDD quickstart guide, GitHub: short and full paths, and the command order.
Frequently Asked Questions
Do I need Spec Kit to do spec-driven development with Claude Code?
No. You can write a spec.md by hand and ask Claude Code to read it before coding; Spec Kit automates the flow and provides templates. To choose, there is the comparison of OpenSpec, Spec Kit and BMAD.
Do I have to go through all the commands for a small feature?
No. The documentation proposes a short path for small features and a full one for production, and the extra steps only pay off when the feature hides decisions that haven’t been made.
Why /speckit-specify in Claude Code and /speckit.specify in the documentation?
It is the same command: the documentation uses a dot as general notation and Claude Code installs it as a skill with a hyphen. If it doesn’t show up, check the folder name in .claude/skills/.
Is there a GitHub Spec Kit tutorial with a complete example?
This very post: it walks through the constitution, the spec, the plan, the tasks and the implementation with a small example, and flags which parts are illustrative. For the exact reference of each command, the source is the official documentation.
What do I do if the agent ignores the spec?
First check that the spec says what you think it says. If it was clear, point to the specific requirement (FR-002) and ask for a failing test before fixing it; if it didn’t cover it, correct the spec and regenerate the plan and tasks.
Does spec-driven development replace tests?
No: the spec says what has to happen and the tests check that it does, like the “Home” against “home” scenario that becomes task T002; the difference between the two approaches is explained in the spec-driven development guide.
If you want to learn to direct agents with this same judgment, from the spec to verification, we work through it step by step in the agentic patterns course.