Spec-Driven Development

Write a structured specification before writing any code. Code without a spec is guessing.

When to Use

• Starting a new project or feature
• Requirements are ambiguous or incomplete
• The change touches multiple files or modules
• You're about to make an architectural decision
• The task would take more than 30 minutes to implement

The Gated Workflow

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

Phase 1: Specify

Start with a high-level vision. Ask clarifying questions until requirements are concrete.

Surface assumptions immediately:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Spec template:

# Spec: [Project/Feature Name]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[Specific, testable conditions]

## Open Questions
[Anything unresolved that needs human input]

Phase 2: Plan

With the validated spec, generate a technical implementation plan:

1. Identify the major components and their dependencies
2. Determine the implementation order
3. Note risks and mitigation strategies
4. Identify parallelization opportunities
5. Define verification checkpoints

Phase 3: Tasks

Break the plan into discrete, implementable tasks:

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm — test command, build, manual check]
  - Files: [Which files will be touched]

Phase 4: Implement

Execute tasks one at a time following incremental implementation and test-driven development.

Keeping the Spec Alive

The spec is a living document:

• Update when decisions change
• Update when scope changes
• Commit the spec alongside the code
• Reference the spec in PRs

Verification

Before proceeding to implementation:

• [ ] The spec covers all six core areas
• [ ] The human has reviewed and approved the spec
• [ ] Success criteria are specific and testable
• [ ] Boundaries (Always/Ask First/Never) are defined
• [ ] The spec is saved to a file in the repository