---
title: Spec Kit + Claude Code Usage Guide
title_en: Spec Kit + Claude Code Usage Guide
description: A full workflow for Spec-Driven Development (SDD) using GitHub Spec Kit — covering the six-stage process, a worked example, and best practices.
sidebar_label: Spec Kit usage guide
---

# Spec Kit + Claude Code Usage Guide

> **Spec-Driven Development (SDD)** — before writing any code, define what the software should do.
> The specification becomes the single source of truth that both humans and AI use to produce code.

---

## Table of Contents

1. [What is Spec Kit?](#1-what-is-spec-kit)
2. [Why SDD?](#2-why-sdd)
3. [Installation and Environment Setup](#3-installation-and-environment-setup)
4. [Project Initialization](#4-project-initialization)
5. [Core Workflow (Six Stages)](#5-core-workflow-six-stages)
6. [Supporting Commands](#6-supporting-commands)
7. [File Structure](#7-file-structure)
8. [Worked Example](#8-worked-example)
9. [Best Practices](#9-best-practices)
10. [When to Use / Not Use](#10-when-to-use--not-use)
11. [Common Pitfalls and Fixes](#11-common-pitfalls-and-fixes)
12. [Advanced Techniques](#12-advanced-techniques)
13. [References](#13-references)

---

## 1. What is Spec Kit?

Spec Kit is GitHub's open-source **Spec-Driven Development toolkit**. It provides a structured process so AI coding agents (Claude Code, GitHub Copilot, Gemini CLI, etc.) can produce code based on explicit specifications.

**Core idea**: a specification is not just documentation — it is an executable development instruction.

**Two components**:

| Component | Description |
|-----------|-------------|
| **Specify CLI** | Command-line tool for initialising projects and downloading templates |
| **Templates + Slash Commands** | Templates and Claude Code commands that define the spec format, the technical-plan structure, and the task-breakdown style |

---

## 2. Why SDD?

### Problems with letting AI write code directly

| Problem | Description |
|---------|-------------|
| **Context loss** | The longer the conversation, the easier it is for the AI to forget earlier agreements |
| **Inconsistent assumptions** | The AI decides based on its own interpretation, which may not match your architecture |
| **Code drift** | Without an explicit spec, the AI tends to add features you didn't ask for or stray from the design |
| **Hard to collaborate** | When several people use AI on the same feature, each writes different prompts and the output is inconsistent |

### How SDD addresses this

- The **Constitution** ensures every AI interaction is anchored to the same set of principles
- The **Specification** removes ambiguous requirements and gives the AI explicit instructions
- The **Plan** embeds architectural constraints so the AI doesn't drift from the design
- **Tasks** break the big problem into small chunks, reducing the AI's error rate
- **Every stage has a checkpoint**, letting you confirm direction before the AI executes

---

## 3. Installation and Environment Setup

### Prerequisites

- **Python 3.11+**
- **uv** (Astral's Python package manager)
- **Git**
- **Claude Code** (installed and runnable)

### Install uv (if you don't have it yet)

```powershell
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### Install Specify CLI (persistent install recommended)

```bash
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
```

### Upgrade

```bash
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
```

### Verify the install

```bash
specify check
```

This checks that git, claude, and other required tools are correctly installed.

---

## 4. Project Initialization

### Initialise in an existing project

```bash
cd your-project
specify init . --ai claude --force
```

### Create a new project

```bash
specify init my-project --ai claude
```

### init options

| Option | Description |
|--------|-------------|
| `--ai claude` | Use Claude Code (also supports copilot, gemini, cursor-agent, etc.) |
| `--script ps` | Use PowerShell scripts (for Windows) |
| `--force` | Skip the non-empty directory prompt |
| `--no-git` | Don't initialise a git repo |

### Structure produced by init

```
your-project/
├── .claude/
│   └── commands/           # Claude Code slash commands
│       ├── speckit.constitution.md
│       ├── speckit.specify.md
│       ├── speckit.clarify.md
│       ├── speckit.plan.md
│       ├── speckit.tasks.md
│       ├── speckit.implement.md
│       ├── speckit.analyze.md
│       ├── speckit.checklist.md
│       └── speckit.taskstoissues.md
├── .specify/
│   ├── memory/
│   │   └── constitution.md  # Project constitution (core principles)
│   ├── templates/           # Templates for each stage
│   │   ├── constitution-template.md
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   ├── tasks-template.md
│   │   ├── checklist-template.md
│   │   └── agent-file-template.md
│   └── scripts/
│       └── powershell/      # Automation scripts
│           ├── check-prerequisites.ps1
│           ├── common.ps1
│           ├── create-new-feature.ps1
│           ├── setup-plan.ps1
│           └── update-agent-context.ps1
└── specs/                   # Per-feature spec docs (created on demand)
```

---

## 5. Core Workflow (Six Stages)

```
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│ Constitution │───>│   Specify   │───>│   Clarify   │
│  (do once)   │    │ (define req) │    │ (resolve fuzz)│
└─────────────┘    └─────────────┘    └──────┬──────┘
                                             │ (optional)
                   ┌─────────────┐    ┌──────▼──────┐
                   │  Implement  │<───│    Plan     │
                   │  (execute)   │    │ (tech plan) │
                   └──────▲──────┘    └──────┬──────┘
                          │                  │
                   ┌──────┴──────┐    ┌──────▼──────┐
                   │   Analyze   │<───│    Tasks    │
                   │ (quality)    │    │ (breakdown) │
                   └─────────────┘    └─────────────┘
```

### Full command sequence

```
/speckit.constitution  →  set once, shared by all features
/speckit.specify       →  describe what you want to build (focus on WHAT & WHY)
/speckit.clarify       →  [optional] AI asks up to 5 clarifying questions
/speckit.plan          →  produce a technical plan (focus on HOW)
/speckit.tasks         →  break it down into an actionable task list
/speckit.analyze       →  [optional] cross-document consistency check
/speckit.implement     →  execute tasks one by one and produce code
```

---

### Stage 1: Constitution

**Purpose**: define the non-negotiable development principles of the project. Done once and shared by all features.

**Run**:
```
/speckit.constitution principles description...
```

**What to put in**:
- Architectural patterns and constraints
- Tech stack requirements
- Naming conventions
- Testing requirements
- Security constraints
- Quality standards

**Example**:
```
/speckit.constitution
1. C# .NET Framework 4.8 + WinForms, no WPF
2. Every Process must inherit clsThreadProc and use the EQRunCase state machine
3. Hardware operations must have timeout and alarm mechanisms
4. Multithreading is coordinated by boolean flags; shared resources are protected by lock
5. Follow existing naming conventions: cls/enu/Proc prefixes
6. UI updates go through clsProjectInvoke for thread safety
```

**Output**: `.specify/memory/constitution.md` (concrete principles filled in, placeholders replaced)

**Key points**:
- Constitution quality directly drives the output quality of every downstream stage
- Explicitly list both "forbidden" patterns and "required" practices
- Include a version number and revision date for traceability

---

### Stage 2: Specify

**Purpose**: describe what feature you want to build, focused on "what" and "why".

**Run**:
```
/speckit.specify feature description...
```

**What to put in**:
- User Stories
- Functional Requirements
- Success Criteria
- Edge Cases

**Example**:
```
/speckit.specify Add a FOUP Mapping feature:
After the operator loads a Cassette at the LD station, the system automatically detects
whether each Slot has a Wafer and shows the Mapping result on the UI. Supports the standard
25-slot Cassette; raises an Alarm on anomalies (e.g. sensor failure); writes the Mapping
result to the Log.
```

**Output**:
- `specs/{N}-{feature-name}/spec.md` — full specification
- `specs/{N}-{feature-name}/checklists/requirements.md` — spec-quality checklist
- A Git feature branch is created automatically

**spec.md contains**:
- User Stories (with priorities P1/P2/P3)
- Acceptance Scenarios (Given/When/Then format)
- Functional Requirements (FR-001, FR-002...)
- Key Entities
- Success Criteria (measurable success indicators)
- Edge Cases

**Key points**:
- **Don't** write implementation details (no frameworks, no APIs, no code structure)
- **Do** describe the feature from the user's point of view
- At most 3 `[NEEDS CLARIFICATION]` markers
- Each User Story must be independently testable

---

### Stage 3: Clarify

**Purpose**: before moving to the technical plan, have the AI detect ambiguous areas in the spec and resolve them through interactive Q&A.

**Run**:
```
/speckit.clarify
```

**How it works**:
1. The AI scans spec.md, doing ambiguity analysis across 10 categories
2. It produces up to 5 clarification questions (ordered by impact)
3. **One question at a time**, with recommended options
4. You can reply with an option code (e.g. "A"), say "yes" to accept the recommendation, or answer freely
5. Each answer is written back into the relevant section of spec.md immediately

**Analysis categories**:
- Functional scope and behaviour
- Data model
- Interaction and UX flow
- Non-functional requirements (performance, security, reliability)
- External integration and dependencies
- Boundaries and exception handling
- Terminology consistency

**When to use**:
- Complex feature → strongly recommended
- Simple feature → can skip, but the AI will warn that risk increases

---

### Stage 4: Plan

**Purpose**: produce a technical implementation plan from the spec, including architecture choices, data model, and project structure.

**Run**:
```
/speckit.plan tech stack and constraints description...
```

**Example**:
```
/speckit.plan Use C# .NET Framework 4.8,
inherit the clsThreadProc state machine pattern,
EtherCAT motion control,
IO accessed via enuDi/enuDo enums
```

**Execution phases**:

| Phase | Output | Description |
|-------|--------|-------------|
| Phase 0 | `research.md` | Resolve all technical unknowns; record decisions and alternatives |
| Phase 1 | `data-model.md` | Entities, fields, relationships, state transitions |
| Phase 1 | `contracts/` | Interface contracts (API, CLI, comms protocol) |
| Phase 1 | `quickstart.md` | Integration scenarios and verification steps |

**plan.md contains**:
- Technical Context (language, dependencies, storage, testing, platform)
- Constitution Check (must pass to continue)
- Project Structure (concrete directory layout)
- Complexity Tracking (any deviations from principles must be justified)

**Key points**:
- During Plan you can ask the AI to produce multiple options for comparison
- Constitution Check is a quality gate — violating a principle is an ERROR
- All `NEEDS CLARIFICATION` items must be resolved in Phase 0

---

### Stage 5: Tasks

**Purpose**: break the plan down into an executable task list, grouped by User Story.

**Run**:
```
/speckit.tasks
```

**Output**: `specs/{N}-{feature-name}/tasks.md`

**Task format**:
```
- [ ] T001 Create project structure per implementation plan
- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py
- [ ] T012 [P] [US1] Create User model in src/models/user.py
```

| Marker | Meaning |
|--------|---------|
| `- [ ]` | Markdown checkbox |
| `T001` | Task number (execution order) |
| `[P]` | Can run in parallel (different files, no dependency) |
| `[US1]` | Maps to User Story 1 |
| Description | Includes concrete file path |

**Phase structure**:
```
Phase 1: Setup         — project init
Phase 2: Foundational  — blocking prerequisites (must finish first)
Phase 3: User Story 1  — P1 highest priority (= MVP)
Phase 4: User Story 2  — P2
Phase N: Polish        — cross-cutting cleanup
```

**Key points**:
- Each User Story can be implemented and tested independently
- MVP = Phase 1 + 2 + 3 (User Story 1) is enough to ship
- `[P]`-marked tasks can run concurrently
- Each task must be concrete enough that the AI doesn't need extra context to execute it

---

### Stage 6: Implement

**Purpose**: produce code task by task from the task list.

**Run**:
```
/speckit.implement
```

**Execution flow**:
1. Check that all checklists pass (asks whether to continue if any fail)
2. Load context: tasks.md, plan.md, data-model.md, etc.
3. Verify / create ignore files (.gitignore, etc.)
4. Execute tasks in Phase order
5. Completed tasks are marked `[X]`
6. After each Phase, run a verification checkpoint

**Key points**:
- Inspect the output of the first 2-3 tasks carefully
- If it drifts from the spec, you can go back to `/speckit.plan` or `/speckit.clarify` to correct course at any time
- `[P]`-marked tasks will attempt to run in parallel
- Failed tasks will stop and report rather than push through

---

## 6. Supporting Commands

### `/speckit.analyze` (consistency analysis)

**Purpose**: do a cross-document quality check before implement (read-only; doesn't modify any files).

**When**: between `/speckit.tasks` and `/speckit.implement`.

**Checks**:

| Category | What it checks |
|----------|----------------|
| Duplication | Near-duplicate requirements |
| Ambiguity | Adjectives without quantitative criteria (fast, scalable, robust) |
| Underspecification | Requirements with verbs but no object or quantified outcome |
| Constitution alignment | Violations of MUST principles (automatically flagged CRITICAL) |
| Coverage gaps | Requirements without matching tasks, tasks without matching requirements |
| Inconsistency | Terminology drift, data-entity desync, task-order contradictions |

**Severity**: CRITICAL > HIGH > MEDIUM > LOW

**Output**: a structured analysis report (Markdown tables) with suggested fixes.

---

### `/speckit.checklist` (quality checklist)

**Purpose**: generate a "requirement-quality checklist" for a specific area, validating whether the requirements themselves are well-written (not whether the implementation is correct).

**Example**:
```
/speckit.checklist security requirements check
/speckit.checklist UX interaction flow requirement quality
/speckit.checklist hardware communication interface requirement completeness
```

**Core concept**: a Checklist is a "unit test for requirements".

```
correct:   "Are keyboard navigation requirements defined for all interactive elements?" [Coverage, Gap]
incorrect: "Verify button click navigates correctly" (that's testing implementation, not testing the requirement)
```

**Output**: `specs/{feature}/checklists/{domain}.md`

---

### `/speckit.taskstoissues` (tasks → GitHub Issues)

**Purpose**: automatically create GitHub Issues from the tasks in tasks.md.

**Prerequisite**: the git remote must be a GitHub URL.

---

## 7. File Structure

```
specs/
└── 1-feature-name/          # One directory per feature
    ├── spec.md               # Feature spec (produced by /speckit.specify)
    ├── plan.md               # Technical plan (produced by /speckit.plan)
    ├── research.md           # Technical research (Plan Phase 0)
    ├── data-model.md         # Data model (Plan Phase 1)
    ├── quickstart.md         # Integration scenarios (Plan Phase 1)
    ├── contracts/            # Interface contracts (Plan Phase 1)
    ├── tasks.md              # Task list (produced by /speckit.tasks)
    └── checklists/           # Quality checklists
        ├── requirements.md   # Spec quality (auto by /speckit.specify)
        ├── security.md       # Security req quality (/speckit.checklist)
        └── ux.md             # UX req quality (/speckit.checklist)

.specify/
├── memory/
│   └── constitution.md       # Project constitution (/speckit.constitution)
├── templates/                # Stage templates (do not edit by hand)
└── scripts/                  # Automation scripts

.claude/
└── commands/                 # Claude Code slash commands
```

---

## 8. Worked Example

### Scenario: add FOUP Mapping to ENR_DUC

#### Step 1: set the Constitution (first time only)

```
/speckit.constitution
1. C# .NET Framework 4.8 + WinForms
2. Every Process inherits clsThreadProc and uses the EQRunCase state machine
3. EtherCAT motion control; IO accessed via enuDi/enuDo enums
4. Hardware operations must have timeout; exceptions must trigger enuAlarm
5. Multithreading coordinated by boolean flags; shared resources via lock
6. Naming conventions: cls/enu/Proc prefixes, Hungarian-style notation
7. UI updates go through clsProjectInvoke for thread safety
8. Every new Process must be registered as a static property on clsEditRunThread
9. Logs go via clsLog.Log(enuLogType_Extend.XXX, message)
```

#### Step 2: define the feature spec

```
/speckit.specify Add a FOUP Mapping feature:
After the operator loads a Cassette at the LD station, the system uses sensors to
automatically detect whether each Slot (1-25) has a Wafer and produces a Mapping result.
The result is shown live on the Cassette icon in the UI
(has Wafer = green, empty = grey, anomaly = red).
After Mapping completes, the result is written to the Recipe Log.
Sensor failure or read anomaly triggers an Alarm.
Supports a Bypass Mapping option (skip in test mode).
```

#### Step 3: clarify (optional)

```
/speckit.clarify
```

The AI might ask:
- Q1: does the Mapping sensor use DI or AI (analog / digital)?
- Q2: should non-standard Cassettes (not 25 slot) be supported?
- Q3: what permission level is needed for Bypass Mapping?

#### Step 4: technical plan

```
/speckit.plan Use the existing clsThreadProc state machine pattern,
DI sensors read via EtherCAT GetDI,
UI is a WinForms UserControl,
add a new ProcLD_Mapping Process
```

#### Step 5: task breakdown

```
/speckit.tasks
```

#### Step 6: consistency check (optional but recommended)

```
/speckit.analyze
```

#### Step 7: execute the implementation

```
/speckit.implement
```

---

## 9. Best Practices

### Constitution is the key

| Practice | Description |
|----------|-------------|
| **The more concrete the better** | "Use clsThreadProc" beats "use a state machine" |
| **List forbidden items** | "Do not set iStepIndex directly; you must use EQRunCase.GoCase()" |
| **Include naming rules** | Cuts down on the AI inventing its own naming |
| **Keep it up to date** | Sync whenever an architectural decision changes |

### Specify from the user's perspective

- Describe "what the operator does", not "how the system implements it"
- Include edge cases (sensor failure, comms drop)
- Each User Story carries a priority
- The more detailed the initial prompt, the less rework later

### The Plan must fit the existing architecture

- Explicitly name the specific files to modify or add
- Reference existing classes and patterns
- Mark integration points with the existing system

### Tasks must be concrete enough

- Each task specifies a concrete file path
- Dependencies between tasks must be clear
- MVP strategy: complete User Story 1 first and ship

### Implement requires supervision

- Carefully review the first 2-3 tasks
- Correct course immediately when drift is detected (go back to plan or clarify)
- Do a human checkpoint after each Phase

---

## 10. When to Use / Not Use

### Good fits

| Situation | Why |
|-----------|-----|
| **New feature module development** | Needs a complete design-to-implementation flow |
| **Complex features (multi-file)** | AI tends to lose control in wide-ranging changes |
| **Multiple people on the same feature** | Shared spec → consistent output |
| **Refactoring a subsystem** | Need to nail down existing behaviour before touching anything |
| **Integrating new hardware / comms protocol** | Strict interface definitions required |

### Poor fits

| Situation | Alternative |
|-----------|-------------|
| **Bug fix** | Just describe the bug and let Claude fix it |
| **Parameter tweaks** | Just change them directly |
| **Single-file small edits** | Just prompt Claude directly |
| **Exploratory prototype** | Vibe-code first; once direction is set, switch to SDD |
| **Emergency hotfix** | Too heavy a process — just fix it |

### Rule of thumb

> **If your change touches 3+ files, requires a new class, or affects multiple subsystems** → consider Spec Kit
>
> **If it can be done by hand in 10 minutes** → just do it

---

## 11. Common Pitfalls and Fixes

| Pitfall | Fix |
|---------|-----|
| **Constitution too vague** | Use specific class names and pattern names, not generic adjectives |
| **Specify includes technical details** | Stay on "what the user does" / "how the system should behave", not "what technology to use" |
| **Skip Clarify and go straight to Plan** | For complex features, run it — it cuts rework later |
| **AI ignores the Constitution** | Quote the constitution principle explicitly in follow-up prompts |
| **Task descriptions too generic** | Add concrete file paths, function names, dependency relationships |
| **Implementing too much at once** | Do the MVP first (User Story 1), verify, then continue |
| **Spec drifts away from code** | When requirements change, update the spec first, then re-run the downstream flow |
| **Context window exhausted** | Consider `/compact` or `/clear` after each stage |
| **AI builds its own components instead of using existing libraries** | Put it in the Constitution: "must use xxx rather than rolling your own" |

---

## 12. Advanced Techniques

### Compare multiple options

During the Plan stage you can ask the AI to produce multiple options:
```
/speckit.plan Please produce two options for comparison:
Option A: add a Mapping sub-flow inside the existing ProcWorker_LD
Option B: create a standalone ProcWorker_Mapping Worker
```

### Incremental delivery

```
Phase 1-2: Setup + Foundation  → foundation ready
Phase 3:   User Story 1 (P1)   → MVP delivered, tested
Phase 4:   User Story 2 (P2)   → second delivery
Phase N:   Polish              → final cleanup
```

You can pause, review, and correct course at every checkpoint.

### Constitution and CLAUDE.md side by side

- **CLAUDE.md**: global preferences (build commands, architecture overview, dev conventions)
- **Constitution**: non-negotiable principles for a specific feature's development

They complement each other and don't conflict. CLAUDE.md handles day-to-day development; the Constitution handles the SDD flow.

### Handling large features

If a feature is too big, break it into multiple independent specs:
```
/speckit.specify FOUP Mapping — sensor reading and data model
/speckit.specify FOUP Mapping — UI display and operator interface
/speckit.specify FOUP Mapping — log records and reports
```

### Environment variables

```bash
# Specify the feature directory when not inside a Git environment
export SPECIFY_FEATURE=1-foup-mapping
```

---

## 13. References

### Official

- [GitHub Spec Kit Repository](https://github.com/github/spec-kit)
- [Spec-Driven Development methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)
- [Quick Start Guide](https://github.com/github/spec-kit/blob/main/docs/quickstart.md)
- [GitHub Blog: Spec-Driven Development with AI](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/)

### Community tutorials

- [Microsoft Developer Blog: Diving Into SDD](https://developer.microsoft.com/blog/spec-driven-development-spec-kit)
- [Agent Factory: SDD with Claude Code (Chapter 5)](https://agentfactory.panaversity.org/docs/General-Agents-Foundations/spec-driven-development)
- [Daniel Ancuta: Building CLI with Spec-Kit and Claude](https://ancuta.org/posts/building-cli-with-spec-kit-and-claude/)
- [LogRocket: Exploring Spec-Driven Development](https://blog.logrocket.com/github-spec-kit/)

### Deep dives

- [Martin Fowler: Understanding SDD Tools (Kiro, Spec-Kit, Tessl)](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
- [DEV Community: Write the Spec, Not the Code](https://dev.to/bobbyblaine/spec-driven-development-write-the-spec-not-the-code-2p5o)

---

## Quick Reference Card

```
command                       when                  output
─────────────────────────────────────────────────────────
/speckit.constitution         project init (once)   .specify/memory/constitution.md
/speckit.specify <desc>       each new feature      specs/{N}-{name}/spec.md
/speckit.clarify              after specify (opt.)  updated spec.md
/speckit.plan <stack>         after clarify         plan.md, research.md, data-model.md
/speckit.tasks                after plan            tasks.md
/speckit.analyze              after tasks (opt.)    analysis report (no file changes)
/speckit.checklist <domain>   anytime (opt.)        checklists/{domain}.md
/speckit.implement            after tasks/analyze   actual code
/speckit.taskstoissues        after tasks (opt.)    GitHub Issues
```

---

*Last updated: 2026-03-09*
*Based on GitHub Spec Kit v0.1.4 + spec-kit-template-claude*