SpecKit: Specification-Driven Development with Claude Code

⚠️ Community Pattern Notice: SpecKit is a community-developed workflow pattern, not an official Claude Code feature. The commands and concepts described here are based on the Claude Bootstrap Kit, a community project that extends Claude Code with custom skills and workflows. Official Claude Code features are documented at docs.anthropic.com.

SpecKit is a specification-driven development framework built on top of Claude Code’s custom skills system. Instead of jumping straight into code, you write specifications first, then Claude implements them systematically with full traceability.

This approach ensures clarity, reduces rework, and creates documentation that stays in sync with code.

Why Specification-Driven Development?

The Problem with Code-First

Developer: "Implement user registration"
Claude: [Implements registration]
Developer: "Actually, I needed email verification"
Claude: [Adds email verification]
Developer: "And it should support SSO"
Claude: [Refactors for SSO]
Developer: "Wait, what about rate limiting?"

Result: Multiple iterations, unclear requirements, no documentation.

The SpecKit Approach

Developer: /speckit-specify User Registration Feature
→ Writes specification with all requirements
→ Clarifies ambiguities
→ Gets approval

Developer: /speckit-plan
→ Technical plan created
→ Architecture decisions documented

Developer: /speckit-implement
→ Claude implements from spec
→ Full traceability
→ Documentation auto-generated

Result: One iteration, clear requirements, complete documentation.

The SpecKit Workflow

┌────────────────────────────────────────────────────────────────┐
│                     SPECKIT WORKFLOW                            │
│                                                                 │
│  ┌──────────────┐                                              │
│  │   SPECIFY    │  Write pure product specification            │
│  │              │  No technical details yet                    │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                              │
│  │   CLARIFY    │  Resolve [NEEDS CLARIFICATION] markers       │
│  │              │  Make product decisions                      │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                              │
│  │    PLAN      │  Technical implementation plan               │
│  │              │  Architecture decisions                      │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                              │
│  │    TASKS     │  Break plan into executable tasks            │
│  │              │  Create implementation roadmap               │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                              │
│  │  IMPLEMENT   │  Execute tasks with full traceability        │
│  │              │  Link code to specifications                 │
│  └──────┬───────┘                                              │
│         │                                                       │
│         ▼                                                       │
│  ┌──────────────┐                                              │
│  │   VALIDATE   │  Verify implementation matches spec          │
│  │              │  Cross-document consistency                  │
│  └──────────────┘                                              │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

SpecKit Commands

Command	Purpose
`/speckit-init`	Initialize SpecKit in project
`/speckit-specify`	Write feature specification
`/speckit-clarify`	Resolve ambiguities
`/speckit-plan`	Create technical plan
`/speckit-tasks`	Break into implementation tasks
`/speckit-implement`	Execute implementation
`/speckit-validate`	Verify implementation
`/speckit`	Run full workflow

Getting Started

Initialize SpecKit

/speckit-init

Creates:

.speckit/
├── constitution.md      # Project principles (9 rules)
├── specifications/      # Feature specifications
├── plans/              # Technical plans
├── tasks/              # Implementation tasks
└── README.md           # SpecKit documentation

The Constitution

SpecKit enforces 9 immutable principles:

# .speckit/constitution.md

## The 9 Principles

### 1. Library-First
All reusable logic lives in libraries, not in CLI or UI code.

### 2. CLI Interface
Features are accessible via CLI before any other interface.

### 3. Test-First
Tests are written before implementation.

### 4. Research-Driven
Decisions are backed by research, not assumptions.

### 5. Specification Consistency
Implementation matches specification exactly.

### 6. Simplicity
Choose the simplest solution that works.

### 7. Anti-Abstraction
Don't abstract until you have 3+ concrete cases.

### 8. Minimal Scope
Implement exactly what's specified, nothing more.

### 9. Integration-First
Integration tests are prioritized over unit tests.

Phase 1: SPECIFY

Writing Specifications

/speckit-specify User Registration Feature

Claude guides you through:

# Specification: User Registration

## Overview
[One paragraph describing the feature]

## User Stories
As a [user type], I want to [action] so that [benefit].

## Acceptance Criteria
- [ ] User can register with email and password
- [ ] Email is validated for format
- [ ] Password meets security requirements
- [ ] Confirmation email is sent
- [ ] User cannot register with existing email

## User Flow
1. User enters email and password
2. System validates input
3. System creates account
4. System sends confirmation email
5. User is redirected to confirmation page

## Edge Cases
- Invalid email format → Show error message
- Weak password → Show requirements
- Existing email → Show "account exists" message
- Email delivery fails → Show retry option

## Out of Scope
- Social login (future feature)
- Two-factor authentication (future feature)
- Password reset (separate spec)

## [NEEDS CLARIFICATION]
- Maximum password length?
- Email template content?
- Redirect destination after registration?

Specification Template

---
id: SPEC-001
title: Feature Name
status: draft | review | approved | implemented
author: Developer Name
created: 2026-01-10
updated: 2026-01-10
---

# Feature Name

## Overview
[What and why]

## User Stories
[Who, what, why]

## Acceptance Criteria
[Testable requirements]

## User Flow
[Step-by-step flow]

## Edge Cases
[Error handling]

## Out of Scope
[What this doesn't include]

## [NEEDS CLARIFICATION]
[Unresolved questions]

## Dependencies
[Other features/specs needed]

## Metrics
[How to measure success]

Phase 2: CLARIFY

Resolving Ambiguities

/speckit-clarify SPEC-001

Claude identifies all [NEEDS CLARIFICATION] markers:

Found 3 items needing clarification:

1. Maximum password length?
   Context: Security requirements for password validation
   Options:
   a) 128 characters (industry standard)
   b) 256 characters (extra safety)
   c) Unlimited (trust the user)

   Recommendation: 128 characters (balances security and usability)

2. Email template content?
   Context: Confirmation email sent to new users
   Decision needed: Marketing wants branded template

3. Redirect destination after registration?
   Context: Where to send user after successful registration
   Options:
   a) Dashboard
   b) Profile setup
   c) Welcome page

Making Decisions

User: "Use 128 char limit, simple text email for now,
       redirect to profile setup."

Claude:
→ Updates specification with decisions
→ Removes [NEEDS CLARIFICATION] markers
→ Adds decision rationale

Updated spec:

## Decisions Made

### Password Length
- **Decision:** 128 character maximum
- **Rationale:** Industry standard, balances security and usability
- **Date:** 2026-01-10

### Email Template
- **Decision:** Simple text email
- **Rationale:** MVP approach, branded template in future phase
- **Date:** 2026-01-10

### Post-Registration Redirect
- **Decision:** Redirect to profile setup
- **Rationale:** Encourages profile completion, improves user experience
- **Date:** 2026-01-10

Phase 3: PLAN

Creating Technical Plan

/speckit-plan SPEC-001

Claude creates a technical plan:

# Technical Plan: User Registration

## Architecture Overview

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Frontend │ —> │ API │ —> │ Database │ │ (React) │ │ (Express) │ │ (Postgres) │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ▼ │ │ ┌─────────────┐ │ │ │ Email │ │ │ │ (Resend) │ │ │ └─────────────┘ │ │ │ └──────────────────────────────────────►│


## Database Schema

```sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  email VARCHAR(255) UNIQUE NOT NULL,
  password_hash VARCHAR(255) NOT NULL,
  email_verified BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE email_verifications (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES users(id),
  token VARCHAR(255) UNIQUE NOT NULL,
  expires_at TIMESTAMPTZ NOT NULL,
  used_at TIMESTAMPTZ
);

API Design

POST /api/auth/register

// Request
{
  email: string;     // Valid email format
  password: string;  // 8-128 chars, complexity requirements
}

// Response (201)
{
  message: "Registration successful. Please check your email.";
  userId: string;
}

// Error (400)
{
  error: "validation_error";
  details: { field: string; message: string }[];
}

// Error (409)
{
  error: "email_exists";
  message: "An account with this email already exists.";
}

Security Considerations

Password Hashing: bcrypt with cost factor 12
Rate Limiting: 5 attempts per email per hour
Token Security: 256-bit random token, 24h expiry
Input Validation: Zod schemas on server

Dependencies

bcrypt - Password hashing
resend - Email delivery
zod - Input validation
prisma - Database ORM

Risks and Mitigations

Risk	Likelihood	Impact	Mitigation
Email delivery fails	Medium	High	Retry queue, fallback provider
Password breach	Low	Critical	bcrypt, no plaintext storage
Rate limit bypass	Low	Medium	IP-based limiting backup


## Phase 4: TASKS

### Breaking Into Tasks

/speckit-tasks SPEC-001


Claude creates executable tasks:

```markdown
# Implementation Tasks: User Registration

## Task Overview

| ID | Task | Priority | Estimate | Dependencies |
|----|------|----------|----------|--------------|
| T1 | Database migration | High | 30 min | None |
| T2 | Validation schemas | High | 30 min | None |
| T3 | Registration API | High | 1 hour | T1, T2 |
| T4 | Email service | High | 45 min | None |
| T5 | Email integration | High | 30 min | T3, T4 |
| T6 | Registration form | Medium | 1 hour | T3 |
| T7 | Integration tests | High | 1 hour | T3, T5 |
| T8 | E2E tests | Medium | 45 min | T6 |

## Task Details

### T1: Database Migration
**Files:** `prisma/migrations/XXXX_add_users.sql`
**Spec Reference:** SPEC-001 > Database Schema

Create migration for:
- users table
- email_verifications table

Acceptance:
- [ ] Migration runs successfully
- [ ] Rollback works

### T2: Validation Schemas
**Files:** `src/lib/validation/auth.ts`
**Spec Reference:** SPEC-001 > API Design

Create Zod schemas for:
- Email validation
- Password validation (8-128 chars, complexity)

Acceptance:
- [ ] Email schema rejects invalid formats
- [ ] Password schema enforces requirements

### T3: Registration API
**Files:** `src/api/auth/register.ts`
**Spec Reference:** SPEC-001 > API Design

Implement POST /api/auth/register:
- Input validation
- Duplicate email check
- Password hashing
- User creation
- Response formatting

Acceptance:
- [ ] Returns 201 on success
- [ ] Returns 400 on validation error
- [ ] Returns 409 on duplicate email

[Continue for T4-T8...]

Phase 5: IMPLEMENT

Executing Tasks

/speckit-implement SPEC-001

Claude implements with traceability:

/**
 * Registration API Handler
 *
 * @spec SPEC-001
 * @task T3
 * @acceptance
 * - Returns 201 on success
 * - Returns 400 on validation error
 * - Returns 409 on duplicate email
 */
export async function registerUser(req: Request, res: Response) {
  // Validate input per SPEC-001 > API Design
  const validation = RegistrationSchema.safeParse(req.body);
  if (!validation.success) {
    return res.status(400).json({
      error: 'validation_error',
      details: validation.error.flatten().fieldErrors
    });
  }

  const { email, password } = validation.data;

  // Check for existing user per SPEC-001 > Edge Cases
  const existingUser = await db.user.findUnique({
    where: { email }
  });

  if (existingUser) {
    return res.status(409).json({
      error: 'email_exists',
      message: 'An account with this email already exists.'
    });
  }

  // Hash password per Technical Plan > Security
  const passwordHash = await bcrypt.hash(password, 12);

  // Create user per SPEC-001 > Database Schema
  const user = await db.user.create({
    data: { email, passwordHash }
  });

  // Send verification email per SPEC-001 > User Flow
  await sendVerificationEmail(user.id, email);

  // Return success per SPEC-001 > API Design
  return res.status(201).json({
    message: 'Registration successful. Please check your email.',
    userId: user.id
  });
}

Traceability Comments

Every implementation links back to specifications:

// @spec SPEC-001
// @task T3
// @acceptance Returns 201 on success

This enables:

Spec Coverage: Which specs are implemented?
Change Impact: What code changes when spec changes?
Audit Trail: Why was this code written?

Phase 6: VALIDATE

Verification

/speckit-validate SPEC-001

Claude verifies:

# Validation Report: SPEC-001

## Specification Coverage

| Acceptance Criteria | Status | Evidence |
|---------------------|--------|----------|
| User can register with email and password | ✅ | T3 implementation |
| Email is validated for format | ✅ | T2 schema |
| Password meets security requirements | ✅ | T2 schema |
| Confirmation email is sent | ✅ | T5 integration |
| User cannot register with existing email | ✅ | T3 duplicate check |

## Test Coverage

| Task | Tests | Passing |
|------|-------|---------|
| T3 Registration API | 8 | 8 ✅ |
| T6 Registration Form | 5 | 5 ✅ |
| T7 Integration Tests | 12 | 12 ✅ |
| T8 E2E Tests | 6 | 6 ✅ |

## Constitution Compliance

| Principle | Status |
|-----------|--------|
| Library-First | ✅ Validation in lib/ |
| Test-First | ✅ Tests written before impl |
| Specification Consistency | ✅ All criteria met |
| Simplicity | ✅ No over-engineering |
| Minimal Scope | ✅ Only specified features |

## Documentation Status

- [x] API documentation generated
- [x] Code comments with spec references
- [x] README updated

## Result: ✅ VALIDATED

Full Workflow Example

# Initialize SpecKit
/speckit-init

# Write specification
/speckit-specify Payment Processing Feature

# Clarify ambiguities
/speckit-clarify SPEC-002

# Create technical plan
/speckit-plan SPEC-002

# Break into tasks
/speckit-tasks SPEC-002

# Implement
/speckit-implement SPEC-002

# Validate
/speckit-validate SPEC-002

Or use the combined command:

/speckit Payment Processing Feature

This runs all phases interactively.

Integration with Other Tools

SpecKit + Memory

# Save decisions to memory
/memory-save

Claude:
→ Saves SPEC-001 decisions to knowledge graph
→ Available in future sessions
→ Searchable for similar features

SpecKit + GitHub

# Create PR with spec reference
/commit-push-pr

Claude:
→ Creates PR with SPEC-001 reference
→ Links to specification document
→ Includes acceptance criteria checklist

Best Practices

1. Specify Before You Code

Good:
/speckit-specify User Authentication
[Write complete spec]
[Get approval]
[Then implement]

Avoid:
[Start coding]
[Realize requirements unclear]
[Refactor repeatedly]

2. Keep Specs Atomic

Good:
- SPEC-001: User Registration
- SPEC-002: User Login
- SPEC-003: Password Reset

Avoid:
- SPEC-001: Complete Authentication System

3. Mark All Ambiguities

Good:
## [NEEDS CLARIFICATION]
- What happens on third failed login?
- Should we lock the account?
- For how long?

Avoid:
[Assuming you know the answer]
[Making product decisions in code]

4. Reference Specs in Code

/**
 * @spec SPEC-001
 * @task T3
 * @acceptance Returns 201 on success
 */

5. Validate Before Merge

/speckit-validate SPEC-001

# Only merge if validated

SpecKit Directory Structure

.speckit/
├── constitution.md              # Project principles
├── specifications/
│   ├── SPEC-001-registration.md
│   ├── SPEC-002-login.md
│   └── SPEC-003-password-reset.md
├── plans/
│   ├── PLAN-001-registration.md
│   ├── PLAN-002-login.md
│   └── PLAN-003-password-reset.md
├── tasks/
│   ├── TASKS-001-registration.md
│   ├── TASKS-002-login.md
│   └── TASKS-003-password-reset.md
└── validation/
    ├── VALID-001-registration.md
    └── ...

Benefits

For Developers

Clear requirements before coding
Reduced rework
Better estimates
Documentation built-in

For Teams

Shared understanding
Consistent quality
Easier onboarding
Knowledge preservation

For Projects

Full traceability
Audit compliance
Change impact analysis
Living documentation

Getting Started

Today:

Run /speckit-init in your project
Write one specification
Follow it through to implementation

This week:

Develop specification templates for common features
Integrate with your review process
Train team on SpecKit workflow

This month:

Full adoption for new features
Retroactive specs for existing features
Measure reduction in rework

SpecKit transforms how you build software—from chaotic iteration to deliberate construction. Write it down, agree on it, then build exactly what you specified.

Note: SpecKit is a community-developed workflow pattern built using Claude Code’s custom skills system. It is not an official Anthropic product. The underlying concepts leverage official Claude Code features like the Task tool, agents, and markdown-based skill definitions.

References:

Claude Code Official Documentation - Official Claude Code features
Claude Code Skills System - How to create custom skills
Community project: Claude Bootstrap Kit