spec-driven-development

Spec-Driven Development

Skill Overview

Spec-Driven Development is a development methodology that involves writing structured specification documents before coding. Through a four-stage gated workflow (Specify → Plan → Tasks → Implement), it ensures that requirements are clear, solutions are feasible, and tasks are actionable. Specification documents serve as the shared source of truth for the development team, preventing rework and misunderstandings caused by ambiguous requirements.

Applicable Scenarios

1. Starting a New Project or Developing a Major Feature

When starting a new project, developing a new feature, or making a significant architectural change, Spec-Driven Development ensures that all participants reach consensus on the goals, technology stack, project structure, coding style, testing strategy, and boundary constraints. The specification document defines what to build, why to build it, and how to determine whether it is complete, making it an essential preparation step before development begins.

2. Scenarios with Ambiguous or Incomplete Requirements

When requirements exist only as vague ideas, are unclear, or contain ambiguities, Spec-Driven Development forces you to clarify assumptions, resolve requirements, and define success criteria before coding. By converting vague requirements into specific, testable conditions (such as “Dashboard LCP < 2.5s” instead of “Make the Dashboard faster”), it prevents rework caused by misunderstandings later in the process.

3. Complex Changes Involving Multiple Files or Modules

When a change involves multiple files or modules, or requires architectural decisions, specification documents help identify component dependencies, determine the implementation order, assess risks, and define verification checkpoints. This ensures that complex projects have a clear technical implementation plan, tasks are executed in dependency order, and parallelizable and sequential work are appropriately divided.

Core Features

Four-Stage Gated Workflow

Spec-Driven Development divides the development process into four strict stages. Each stage must undergo manual review and validation before proceeding to the next: Specify (Write the Specification) → Plan (Create the Plan) → Tasks (Break Down the Tasks) → Implement (Implementation). This gating mechanism prevents coding from beginning when requirements are unclear or implementation from beginning before the plan has been validated, ensuring that every stage has clear objectives and acceptance criteria.

Specification Document Template and Success Criteria

The skill provides a complete specification document template covering goals, technology stack, commands, project structure, coding style, testing strategy, and boundary constraints (Always/Ask First/Never). It places particular emphasis on converting vague requirements into specific success criteria—for example, turning “Make the Dashboard faster” into testable conditions such as “Dashboard LCP < 2.5s on 4G, initial data load < 500ms, CLS < 0.1”—so that development has clear completion criteria.

Living Documents and Project Conventions

Specification documents are not one-time documents. They are living documents that should be continuously updated as decisions change, scope is adjusted, and features are added or removed. They should be committed to version control and referenced in pull requests. The skill also defines project boundaries: which actions must always be performed (such as running tests before committing), which require prior approval (such as modifying the database schema or adding dependencies), and which must never be performed (such as committing secrets or deleting failing tests), providing the team with clear operational guidance.

Frequently Asked Questions

What is Spec-Driven Development? Why use it?

Spec-Driven Development is a development methodology in which a structured specification document is created before writing code. The specification document defines what to build, why to build it, and how to determine whether it is complete, serving as the shared source of truth for the development team. Using Spec-Driven Development helps prevent rework and misunderstandings caused by ambiguous requirements, unstated assumptions, and undocumented architectural decisions—a 15-minute specification planning session can prevent hours of debugging and rework.

What should a technical specification document contain?

A specification document should contain six core sections: 1) Goals—what to build and why, who the users are, and what the success criteria are; 2) Technology Stack—frameworks, languages, key dependencies, and versions; 3) Commands—complete build, test, lint, and development commands; 4) Project Structure—the directory layout for source code, tests, and documentation; 5) Coding Style—naming conventions, formatting rules, and code examples; and 6) Testing Strategy—which frameworks to use, where tests should be located, coverage requirements, and testing levels. It should also define boundaries (Always/Ask First/Never) and open questions.

Do small projects or simple tasks also need specification documents?

Yes, but the length of the specification should match the complexity of the task. A simple task may need only two lines of specification (for example, acceptance criteria and boundaries), but it still needs clear completion criteria. Only one-line fixes, spelling corrections, or changes with clear and self-contained requirements may skip the specification. All tasks requiring more than 30 minutes of implementation time, changes involving multiple files, or work requiring architectural decisions should begin with a specification document.