spec-driven-development

Spec-Driven Development

Overview

Write a structured specification before writing any code. A spec answers three questions: what are we building, why are we building it, and how will we know it's done? Every hour spent on a spec saves multiple hours of rework. Never start implementation without a written, reviewed spec.

When to Use

• Starting a new project, feature, or significant change
• Requirements are unclear, ambiguous, or stated as a vague idea
• Multiple possible approaches exist and the tradeoffs need documenting
• The change touches more than two files or crosses a system boundary

When NOT to use: Trivial bug fixes with a clear, single-line root cause, or changes where the spec already exists and is current.

The Spec Process

Step 1: Interview First (If the Ask Is Vague)

Before writing the spec, gather enough context to write it well:

• What problem does this solve for the user?
• Who are the users, and what do they currently do instead?
• What does success look like? How will we measure it?
• Are there any hard constraints (perf, security, compatibility, deadline)?
• What's explicitly out of scope?

Do not write the spec until you can answer these with confidence.

Step 2: Write the Spec

A spec has six sections:

# Spec: [Feature Name]

## Objective
One paragraph: what problem this solves and for whom. Include the measurable
success condition (e.g., "users can reset their password without contacting support").

## Commands / User Flows
The primary interactions from the user's point of view. Use imperative language:
- User navigates to /reset-password
- User enters email address and submits
- User receives email with a time-limited link
- User sets a new password via the link

## Project Structure
Which files and modules will change or be created. Group by layer (API, frontend, DB).
Note any new dependencies.

## Code Style and Patterns
- Which existing patterns to follow (e.g., "use the existing AuthService pattern")
- Naming conventions for new symbols
- Error handling approach

## Testing Strategy
- What will be unit tested
- What requires integration tests
- Any E2E coverage needed
- Edge cases to cover explicitly

## Boundaries
- Always: [things the implementation must always do]
- Ask first: [decisions that require human sign-off before proceeding]
- Never: [things the implementation must never do]