Skip to main content

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?
  2. Why SDD?
  3. Installation and Environment Setup
  4. Project Initialization
  5. Core Workflow (Six Stages)
  6. Supporting Commands
  7. File Structure
  8. Worked Example
  9. Best Practices
  10. When to Use / Not Use
  11. Common Pitfalls and Fixes
  12. Advanced Techniques
  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:

ComponentDescription
Specify CLICommand-line tool for initialising projects and downloading templates
Templates + Slash CommandsTemplates 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​

ProblemDescription
Context lossThe longer the conversation, the easier it is for the AI to forget earlier agreements
Inconsistent assumptionsThe AI decides based on its own interpretation, which may not match your architecture
Code driftWithout an explicit spec, the AI tends to add features you didn't ask for or stray from the design
Hard to collaborateWhen 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)​

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

Upgrade​

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

Verify the install​

specify check

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

4. Project Initialization​

Initialise in an existing project​

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

Create a new project​

specify init my-project --ai claude

init options​

OptionDescription
--ai claudeUse Claude Code (also supports copilot, gemini, cursor-agent, etc.)
--script psUse PowerShell scripts (for Windows)
--forceSkip the non-empty directory prompt
--no-gitDon'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:

PhaseOutputDescription
Phase 0research.mdResolve all technical unknowns; record decisions and alternatives
Phase 1data-model.mdEntities, fields, relationships, state transitions
Phase 1contracts/Interface contracts (API, CLI, comms protocol)
Phase 1quickstart.mdIntegration 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
MarkerMeaning
- [ ]Markdown checkbox
T001Task number (execution order)
[P]Can run in parallel (different files, no dependency)
[US1]Maps to User Story 1
DescriptionIncludes 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:

CategoryWhat it checks
DuplicationNear-duplicate requirements
AmbiguityAdjectives without quantitative criteria (fast, scalable, robust)
UnderspecificationRequirements with verbs but no object or quantified outcome
Constitution alignmentViolations of MUST principles (automatically flagged CRITICAL)
Coverage gapsRequirements without matching tasks, tasks without matching requirements
InconsistencyTerminology 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
/speckit.analyze

Step 7: execute the implementation​

/speckit.implement

9. Best Practices​

Constitution is the key​

PracticeDescription
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 rulesCuts down on the AI inventing its own naming
Keep it up to dateSync 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​

SituationWhy
New feature module developmentNeeds a complete design-to-implementation flow
Complex features (multi-file)AI tends to lose control in wide-ranging changes
Multiple people on the same featureShared spec → consistent output
Refactoring a subsystemNeed to nail down existing behaviour before touching anything
Integrating new hardware / comms protocolStrict interface definitions required

Poor fits​

SituationAlternative
Bug fixJust describe the bug and let Claude fix it
Parameter tweaksJust change them directly
Single-file small editsJust prompt Claude directly
Exploratory prototypeVibe-code first; once direction is set, switch to SDD
Emergency hotfixToo 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​

PitfallFix
Constitution too vagueUse specific class names and pattern names, not generic adjectives
Specify includes technical detailsStay on "what the user does" / "how the system should behave", not "what technology to use"
Skip Clarify and go straight to PlanFor complex features, run it — it cuts rework later
AI ignores the ConstitutionQuote the constitution principle explicitly in follow-up prompts
Task descriptions too genericAdd concrete file paths, function names, dependency relationships
Implementing too much at onceDo the MVP first (User Story 1), verify, then continue
Spec drifts away from codeWhen requirements change, update the spec first, then re-run the downstream flow
Context window exhaustedConsider /compact or /clear after each stage
AI builds its own components instead of using existing librariesPut 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​

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

13. References​

Official​

Community tutorials​

Deep dives​

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