A new development paradigm

Write the spec.
The code follows.

Spec-Driven Development is a methodology where the spec is the requirement, the test contract, and the documentation — all in one file. Before any line of code is written.

Learn More View on GitHub
📋
Spec
Define intent
→
⚙️
Skills
Set constraints
→
🤖
Synthesize
Generate code
→
🧪
Validate
Test vs spec
→
👁️
Govern
Human review
→
🚀
Ship
Production
The Concept

What is SDD?

SDD sits alongside TDD, BDD, and DDD as a development paradigm. Each answers a different question.

Spec-First Concept — a Markdown spec transforming into tests, code, and documentation
TDD
Test-Driven Development
"How do I verify it works?"
First artifact: Test
BDD
Behavior-Driven Development
"How should it behave?"
First artifact: Behavior
DDD
Domain-Driven Design
"How do I model the domain?"
First artifact: Domain Model
SDD
Spec-Driven Development
"What should it do?"
First artifact: Spec
SDD encompasses TDD: the spec contains test scenarios. A team using SDD is inherently doing TDD — but with a richer, more accessible source of truth that everyone on the team can read and write.
The Problem

Requirements live everywhere
except where they should

Traditional Development vs Spec-Driven Development comparison

Traditional Development

  • ✗
  • ✗
  • ✗
  • ✗
  • ✗
  • ✗
"That's not what I meant."

Spec-Driven Development

  • ✓
  • ✓
  • ✓
  • ✓
  • ✓
  • ✓
Single source of truth. Always.
Foundation

Five Principles

01

Spec-First

No code exists without a spec. The spec defines inputs, outputs, errors, side-effects, and test scenarios — before any implementation.

02

Human Governance

AI synthesizes code, but humans define constraints (skills/rules) and approve the output. Every piece of code passes through human review.

03

Validation Against Contract

Code is done when it passes all test scenarios in the spec — not when the developer says so. The spec is the contract.

04

Tool-Agnostic

SDD works with Cursor, Copilot, CI/CD pipelines, custom engines, or a developer writing code by hand. The spec is the universal input.

05

Evolvable

Specs are versioned. When business rules change, the spec is updated. The code evolves to match. The spec governs the code, not the other way around.

The Core Artifact

The Spec

A Markdown file that anyone on the team can write. It defines what the software should do, how to test it, and serves as living documentation.

specs/user.md 
# POST /user

## Auth
None

## Description
Creates a new user. Validates email format,
hashes password with bcrypt, returns JWT.

## Input
- email (string, required, email format)
- passkey (string, required, min 8 chars)

## Output (201)
- token (string, JWT)
- userData
  - id (uuid)
  - email (string)
  - created_at (datetime)

## Errors
- 409: Email exists → USER_ALREADY_EXISTS
- 422: Invalid email → INVALID_EMAIL
- 422: Weak password → WEAK_PASSKEY

## Test Scenarios

### Happy Path
Input: { "email": "[email protected]", "passkey": "securePass123" }
Expect: status 201, body contains token
DB: users table has record with email [email protected]

### Duplicate Email
Seed: insert user with email [email protected]
Input: { "email": "[email protected]", "passkey": "secure123" }
Expect: status 409
📝

It's the Requirement

What the endpoint does, what it receives, what it returns. No ambiguity.

🧪

It's the Test Suite

Scenarios with input, expected output, and database assertions. Executable contracts.

📖

It's the Documentation

Always up to date. If the spec changes, the code must change. It can never be outdated.

Guardrails

Skills & Rules

Specs define what to build. Skills define how to build it. Architectural constraints that every piece of code must follow.

Skills and Rules acting as guardrails for code generation
🏗️

Architecture

"Every endpoint must follow DDD: Handler → Service → Repository"

🔒

Security

"Never use raw SQL. Always use parameterized queries. Bcrypt cost 12 minimum."

✅

Validation

"Always validate and sanitize all user input. Never trust the client."

📦

Dependencies

"All dependencies injected via constructor. Never instantiate directly."

🧪

Testing

"Generate unit tests for every service. Edge cases must be covered."

📛

Naming

"Use language conventions. Interfaces don't have I prefix. Constructors are New*."

Skills are portable

Cursor → .cursor/rules/
CI/CD → LLM system prompt
Copilot → instructions.md
Manual → coding standards

Write once, use everywhere. Skills are Markdown files — not tied to any tool.

Process

The Workflow

The SDD workflow pipeline — from spec to production
1

Write the Spec

PM, frontend dev, or backend dev writes a Markdown file defining the feature: inputs, outputs, errors, side-effects, and test scenarios.

Who: Anyone on the team
2

Review the Spec

The spec is reviewed in a Pull Request, just like code. The team verifies business rules, edge cases, and API contracts.

Who: The team (via PR)
3

Synthesize Code

Code is generated following the spec and skills. By Cursor, by a CI/CD pipeline calling an LLM, or by a developer writing by hand.

Who: AI tool or developer
4

Validate Against Spec

The code is executed against the spec's test scenarios. If the output matches the expected contract, the code is valid.

Who: Automated tests
5

Human Review

A developer reviews the code for logic, security, and architecture. Feedback feeds back into the synthesis for correction.

Who: Backend dev / Tech lead
6

Ship to Production

Approved code is merged and deployed. The spec remains as living documentation. When the spec changes, the cycle restarts.

Who: CI/CD pipeline
Roles

Who Does What

SDD democratizes feature definition. Everyone contributes at their level of expertise.

Who does what — PM, Frontend, and Backend roles in SDD
👔

Product Manager

Defines the "What"

Writes business rules in natural language. "When the user registers, return a token. If the email exists, return an error."

🎨

Frontend Dev

Defines the "Interface"

Defines input/output schemas. What the API receives and returns. Error codes the UI needs to handle.

💻

Backend Dev

Defines the "How"

Writes skills/rules, defines security constraints, reviews generated code. Evolves from code writer to architecture curator.

Analysis

Why SDD?

Aspect Traditional SDD
Requirements Jira tickets, meetings, Slack Spec file in the repo
Tests Written after code (or never) Defined before code (in the spec)
Documentation Separate doc (usually outdated) The spec IS the documentation
Consistency Depends on the developer Enforced by skills
Traceability Check Slack / memory Git blame on spec file
Onboarding "Read the code" "Read the specs"
3x
Faster feature definition
Spec replaces meetings + Jira + Confluence
100%
Test coverage guaranteed
No code without test scenarios in the spec
0%
Outdated documentation
The spec IS the doc — always in sync
Start Now

Adopt SDD in 30 Minutes

1
mkdir -p .sdd/specs .sdd/skills

Create the SDD structure in your project

2
Write your first spec in .sdd/specs/user.md

Define inputs, outputs, errors, and test scenarios

3
Write 2-3 skills in .sdd/skills/

Codify your architecture decisions and security rules

4
Develop following the spec

With AI tools or by hand — the spec is the universal input

5
Validate: does the code match the spec?

Run test scenarios. If they pass, you're done.