sdd-kit

Spec-Driven Development for Claude Code — language-agnostic, works with any project.

The biggest engineering orgs (Amazon's six-pagers, Google's design docs, Stripe's RFCs) have always written specs before code. sdd-kit brings that discipline to Claude Code — structured specs in, quality code out.

You describe what to build  →  sdd-kit structures the spec  →  Claude Code executes it

Not a code generator. A clarity tool. The spec is the source of truth. Claude Code is the execution engine.

Requirements

• Claude Code — the execution engine. Install: npm install -g @anthropic-ai/claude-code
• Node.js >= 18
• Optional: ANTHROPIC_API_KEY env var for faster SDK mode (bypasses Claude Code CLI for spec generation)

Without Claude Code, sdd-kit works in prompt-only mode (--prompt-only) — it generates structured prompts you can paste into any AI tool.

Install

npm install -g sdd-kit

Or run without installing:

npx sdd-kit --help

Language: sdd-kit detects your system language. Set SDD_LANG=es for Spanish or SDD_LANG=en for English.

Quick start

Existing project (already has code)

If you have an existing codebase and want to document it first:

# 1. Document your existing code modules
sdd spec document src/
sdd spec document src/auth/
sdd spec document src/services/api.ts

# 2. Generate architecture views from what exists
sdd arch

# 3. Initialize SDD (creates steering docs + updates CLAUDE.md)
#    Use --auto to generate steering from map specs
sdd init --auto

# 4. Now create specs for new features
sdd spec create "Add real-time notifications" --size medium

New project (starting from scratch)

# 1. Initialize SDD structure
sdd init

# 2. Edit the steering files with your project context
#    .claude/steering/product.md   - what this project is
#    .claude/steering/tech.md      - your stack
#    .claude/steering/structure.md - how code is organized

# 3. Create your first spec
sdd spec create "JWT authentication for API endpoints" --size medium

# 4. Execute tasks from the spec
sdd spec execute feat-jwt-authentication

# 5. Check progress
sdd spec status

# 6. Generate architecture views
sdd arch

How documentation stays up to date

sdd-kit keeps documentation in sync with code through automatic refresh at every step:

| Event | What gets updated | |-------|-------------------| | sdd spec execute completes a task | Project map specs for ALL changed directories are refreshed (via git diff), steering docs are updated | | sdd spec create generates a new spec | Steering docs are updated with the new feature | | sdd spec refresh (manual) | All project map specs are regenerated from current code | | sdd arch | Architecture views + dashboard rebuilt from all specs |

Living documentation flow:

Code changes --> project map updates --> steering docs update --> arch views update
     (auto)           (auto)                 (auto)                (on demand)

Project map (specs/_map/) is auto-generated per directory. Steering docs (.claude/steering/) are auto-refreshed after spec operations. Architecture views (specs/_arch/) are rebuilt on sdd arch. The only manual step is running sdd arch when you want an updated dashboard.

How it works

sdd-kit creates and manages structured Markdown specs in your repo:

your-project/
├── CLAUDE.md                  # Auto-updated with SDD section on `sdd init`
├── .claude/
│   └── steering/              # Project context (auto-refreshed)
│       ├── product.md         # Vision, users, goals
│       ├── tech.md            # Stack, infra, constraints
│       └── structure.md       # Code organization, conventions
├── specs/
│   ├── _map/                  # Living project map (auto-generated)
│   │   ├── src--auth.spec.md  # One spec per directory
│   │   ├── src--services.spec.md
│   │   └── ...
│   ├── features/              # One folder per feature
│   │   └── feat-jwt-auth/
│   │       ├── requirements.md    # User stories + acceptance criteria
│   │       ├── design.md          # Architecture, diagrams, API contracts
│   │       └── tasks.md           # Atomic tasks with checkboxes
│   └── _arch/                 # Generated architecture views
│       ├── architecture.md    # Mermaid diagrams (renders on GitHub)
│       ├── architecture.json  # Structured summary data
│       └── dashboard.html     # Interactive visual dashboard

Everything is Markdown. Everything lives in git. No lock-in.

Commands

sdd init

Scaffolds the SDD structure in your project. Creates .claude/steering/ with template files, specs/features/ directory, and adds an SDD section to CLAUDE.md so Claude always knows about your documentation.

# Template steering docs (manual edit)
sdd init

# Auto-generate steering from existing map specs
sdd init --auto

Safe to run multiple times — skips existing steering files, updates CLAUDE.md section idempotently.

sdd spec document <path>

Reverse-engineers existing code into a map spec. This is the starting point for existing projects — document what you have before planning what to build.

# Document a directory
sdd spec document src/auth/

# Document a specific file
sdd spec document app/services/rag_service.py --name rag-service

# Without Claude Code
sdd spec document src/components/ --prompt-only

Output goes to specs/_map/. These specs are used as context for sdd arch, sdd init --auto, and sdd spec create.

sdd spec create <description>

Generates spec files from a feature description. The CLI adapts to the size of the change:

| Size | Files generated | When to use | |------|----------------|-------------| | small | tasks.md only | Bug fixes, tweaks, refactors | | medium | requirements.md + tasks.md | Clear features (1-3 days) | | large | requirements.md + design.md + tasks.md | Complex features, new architecture |

# Bug fix — just tasks, no ceremony
sdd spec create "Fix 422 error on login endpoint" --size small

# Medium feature — requirements + tasks
sdd spec create "Add JWT refresh tokens" --size medium

# Complex feature — full spec with design doc (default)
sdd spec create "Hybrid RAG search pipeline"

# Custom name
sdd spec create "WhatsApp webhook integration" --name whatsapp-hooks

# Without Claude Code — saves a prompt file
sdd spec create "User dashboard" --prompt-only

The CLI detects bug-fix keywords (fix, bug, crash, patch) and suggests using --size small when you use large for what looks like a small change.

sdd spec status [spec-name]

Shows project progress with visual indicators.

# All specs overview
sdd spec status

# Output:
# SDD Project Status
#
#   3 specs · 5/12 tasks · ████████░░░░░░░░░░░░ 42%
#
#   feat-jwt-auth              RDT  ████████████████ 3/3 done
#   feat-rag-search            RDT  ████████░░░░░░░░ 2/5 40%
#   feat-whatsapp-hooks        RDT  ░░░░░░░░░░░░░░░░ 0/4 planned

# Single spec with task details
sdd spec status feat-rag-search --verbose

Indicators: R = requirements.md, D = design.md, T = tasks.md (green = exists, dim = missing).

sdd spec execute <spec-name>

Executes the next pending task via Claude Code. Sends the task description along with requirements, design, and module context so Claude has full understanding. After execution, automatically refreshes map specs for changed directories.

# Next pending task
sdd spec execute feat-jwt-auth

# Specific task
sdd spec execute feat-jwt-auth --task 1.2

# Preview without executing
sdd spec execute feat-rag-search --dry-run

sdd spec refresh [dir]

Manually refreshes map specs (living documentation). Useful after making changes outside of sdd spec execute.

# Refresh all map specs
sdd spec refresh

# Refresh one directory
sdd spec refresh src/core

sdd arch

Generates architecture views from all specs, module docs, and steering docs. Produces:

• architecture.md — Mermaid diagrams that render directly on GitHub
• architecture.json — Structured data (components, features, tech stack)
• dashboard.html — Interactive HTML dashboard with system overview, service map, module breakdown, feature flows, and progress stats

# Generate architecture views
sdd arch

# Without Claude Code
sdd arch --prompt-only

# Open the dashboard
open specs/_arch/dashboard.html

Built for Claude Code

sdd-kit is designed specifically for Claude Code. Every command leverages Claude Code's full project understanding — it reads your files, follows your CLAUDE.md conventions, and writes code that fits your codebase.

| Mode | When | What happens | |------|------|-------------| | Claude Code | claude CLI installed | Full execution — reads project, generates specs, writes code, updates docs | | SDK | ANTHROPIC_API_KEY set | Fast mode — uses Anthropic API directly for spec generation (no code execution) | | Prompt-only | --prompt-only flag | Saves structured prompts you paste into any AI tool |

# Claude Code mode (default) — full power
sdd spec create "Add caching layer"
sdd spec execute feat-caching

# Prompt-only — works without Claude Code
sdd spec create "Add caching layer" --prompt-only

Why Claude Code? Because a raw API call sees nothing but the prompt. Claude Code sees your entire project, your conventions, your existing code. The specs sdd-kit generates become Claude Code's instructions — structured context that produces better code.

Task format

Tasks in tasks.md follow this format:

- [ ] **1.1** Create User model `app/models/user.py`
- [x] **1.2** Add login endpoint `app/routers/auth.py` <- Req 1.1
- [ ] **2.1** Write integration tests `tests/test_auth.py`

Each task has: checkbox, numbered ID, description, optional file path, optional requirement reference. The spec-reader parses this exact format for progress tracking and execution.

Spec sizes: why it matters

"Using a full SDD workflow for a bug fix is like using a sledgehammer to crack a nut." — Birgitta Boeckeler, Thoughtworks (Martin Fowler's blog)

Not every change needs three documents. A typo fix doesn't need acceptance criteria. A one-line bug fix doesn't need an architecture diagram. The --size flag adapts the ceremony to the change:

• small: You know exactly what to do. Just need to track the tasks.
• medium: Requirements are clear, but you want documented acceptance criteria before implementation.
• large: The problem space is complex. You need to think through architecture, data models, and API contracts before writing code.

Works with any project

sdd-kit reads only Markdown. It doesn't parse your code, import your modules, or require any specific language or framework. Use it with:

• React / Next.js / Vue
• FastAPI / Django / Express
• Rails / Laravel / Spring
• Mobile apps, CLI tools, infrastructure
• Any language, any framework

Project structure

sdd-kit/
├── bin/sdd.js                  # CLI entry point
├── src/
│   ├── cli.js                  # Commander setup
│   ├── core/
│   │   ├── generator.js        # Claude Code CLI invocation + prompt fallback
│   │   ├── claude-api.js       # Claude API engine (alternative to CLI)
│   │   ├── spec-reader.js      # Read/parse specs from disk
│   │   ├── scanner.js          # Project directory scanner
│   │   ├── git-changes.js      # Git diff detection for smart refresh
│   │   └── progress.js         # Progress indicator for streaming
│   └── commands/
│       ├── init.js             # Init + CLAUDE.md integration + steering refresh
│       ├── arch.js             # Architecture views + dashboard
│       └── spec/
│           ├── create.js       # Create feature specs
│           ├── document.js     # Reverse-engineer code into specs
│           ├── execute.js      # Execute tasks from specs
│           ├── refresh.js      # Refresh map specs
│           └── status.js       # Show progress
├── templates/
│   ├── arch-dashboard.html     # HTML dashboard template
│   └── steering/               # Init templates
└── package.json

Contributing

# Clone and install
git clone https://github.com/icurbe/sdd-kit.git
cd sdd-kit
npm install

# Run locally
node bin/sdd.js --help

# Link for global testing
npm link
sdd --help

License

MIT — iCurbe