Spec-Driven Development

The biggest mistake with AI coding assistants? Jumping straight into implementation. Spec-driven development flips this: plan thoroughly, then execute precisely.

The Problem with “Vibe Coding”

When you say “add a login feature” and let Claude figure it out:

Claude makes assumptions (wrong ones)
You correct them mid-implementation
Context fills with back-and-forth
Code gets rewritten multiple times
Final result is inconsistent

The Spec-Driven Approach

Plan → Specify → Approve → Implement

Spend 30% of your time planning. Save 70% on implementation and debugging.

The Basic Flow

Start with intent, not implementation

> I need to add user authentication to this API

Let Claude interview you

> Before implementing, interview me about the requirements
> using questions to clarify all decisions

Answer the questions

Claude asks about JWT vs sessions, refresh tokens, password policies, etc.
Review the generated spec

Claude produces a detailed specification. Review and refine.
Approve and implement
```
> This spec looks good. Implement it.
```

What Makes a Good Spec?

A spec should answer these questions:

Functional Requirements

What does it do?
What are the inputs and outputs?
What are the edge cases?
What errors can occur?

Technical Decisions

What patterns/architecture?
What libraries/frameworks?
How does it integrate with existing code?
What are the performance requirements?

Acceptance Criteria

How do we know it’s done?
What tests prove it works?
What does success look like?

Example: Full Spec

# User Authentication Spec

## Overview
Add JWT-based authentication to the REST API.

## Functional Requirements

### Registration (POST /api/auth/register)
- Input: email, password, name
- Validation:
  - Email: valid format, unique
  - Password: min 8 chars, 1 uppercase, 1 number
  - Name: 2-100 characters
- Output: user object (no password)
- Errors: 400 (validation), 409 (duplicate email)

### Login (POST /api/auth/login)
- Input: email, password
- Output: { access_token, refresh_token, expires_in }
- Errors: 401 (invalid credentials)
- Rate limit: 5 attempts per minute per IP

### Refresh (POST /api/auth/refresh)
- Input: refresh_token
- Output: { access_token, expires_in }
- Errors: 401 (invalid/expired token)

### Logout (POST /api/auth/logout)
- Input: refresh_token
- Action: Invalidate refresh token
- Output: 204 No Content

## Technical Decisions

### JWT Configuration
- Access token: 15 minutes expiry
- Refresh token: 7 days expiry
- Algorithm: HS256
- Secret: from environment variable JWT_SECRET

### Password Storage
- Bcrypt with cost factor 12
- Never log or return passwords

### Token Storage
- Refresh tokens stored in Redis
- Key: `refresh:{user_id}:{token_hash}`
- TTL: 7 days

## Files to Create/Modify
- app/routes/auth.py (new)
- app/services/auth_service.py (new)
- app/models/user.py (modify: add password_hash)
- tests/test_auth.py (new)

## Acceptance Criteria
- [ ] Can register new user
- [ ] Can login with valid credentials
- [ ] Cannot login with invalid credentials
- [ ] Access token grants access to protected routes
- [ ] Refresh token generates new access token
- [ ] Expired access token returns 401
- [ ] Rate limiting prevents brute force
- [ ] All endpoints have tests

Creating Specs with Claude

Method 1: Interactive Interview

> I want to add payment processing with Stripe
> Interview me to create a detailed spec before implementing

Claude will use the AskUserQuestion tool to gather requirements.

Method 2: Expand a Brief

> Here's a rough idea:
> - Add Stripe payments
> - Support subscriptions and one-time purchases
> - Handle webhooks for payment events
>
> Expand this into a detailed specification

Method 3: Template-Based

> Create a spec for adding email notifications using this template:
>
> ## Overview
> ## Functional Requirements
> ## Technical Decisions
> ## Files to Change
> ## Acceptance Criteria

The Handoff: Spec to Implementation

Once you have a spec, start fresh:

# Save the spec
> save this spec to docs/specs/auth-spec.md

# Clear context
> /clear

# Or start new session
exit
claude

# Implement from spec
> implement the specification in docs/specs/auth-spec.md

Frameworks for Spec-Driven Development

If you want more structure, explore these frameworks:

GitHub Spec Kit

A lightweight CLI toolkit with four phases:

Specify - Define what and why
Plan - Technical design
Tasks - Break into actions
Implement - Execute with AI

npx github-spec-kit init

BMAD Method

A comprehensive multi-agent framework with specialized roles:

Analyst Agent (requirements)
PM Agent (planning)
Architect Agent (design)
Developer Agent (implementation)

npx bmad-method install

Agent OS

A spec-driven system designed for Claude Code:

# Uses Claude Code commands for orchestration

When to Use Spec-Driven Development

✅ Good Fit

New features with multiple components
Architectural changes
Anything touching auth, payments, or data
Work that will be reviewed by others
Features you’ll need to maintain

❌ Overkill

Simple bug fixes
One-line changes
Exploratory coding
Throwaway prototypes

Tips for Better Specs

1. Include Examples

### Example Request
POST /api/orders
{
  "items": [{"product_id": "123", "quantity": 2}],
  "shipping_address": {...}
}

### Example Response
{
  "order_id": "ord_abc123",
  "status": "pending",
  "total": 4999
}

2. Specify Error Cases

### Errors
| Status | Code | When |
|--------|------|------|
| 400 | INVALID_INPUT | Missing required fields |
| 404 | PRODUCT_NOT_FOUND | Product doesn't exist |
| 409 | INSUFFICIENT_STOCK | Not enough inventory |

3. Define Non-Functional Requirements

### Performance
- Response time: < 200ms p95
- Support: 100 concurrent requests

### Security
- All endpoints require authentication
- Rate limit: 60 requests/minute