mcpskills.net
← Back to Skills
Development

Spec-Driven Development

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet.

by Addy OsmaniRepository →Source →

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