Spec-Driven Development

What Is Spec-Driven Development?

Spec-driven development is a disciplined approach to software design that mandates writing a detailed specification before any code is written. The specification - commonly referred to as the "spec" - acts as a contract between the engineering team and stakeholders, clearly outlining what will be built, the rationale behind it, and the criteria for completion. With this technique, development is never based on vague requirements or assumptions. Instead, the process is methodical, transparent, and review-driven, ensuring clarity and shared understanding before implementation begins.

This skill is particularly relevant for engineers and teams who want to minimize miscommunication, reduce rework, and improve overall project outcomes. By front-loading the work of clarifying requirements, it helps avoid costly changes later in the project lifecycle.

Why Use Spec-Driven Development?

The primary advantage of spec-driven development is the reduction of risk associated with ambiguity. Software projects often fail or experience significant delays due to unclear requirements, misunderstood goals, or hidden assumptions. Spec-driven development solves these problems by:

• Forcing early discovery of unknowns and ambiguities.
• Providing a single, authoritative reference for what is being built.
• Making complex changes more predictable and less error-prone.
• Facilitating easier onboarding for new contributors, since the intent and plan are thoroughly documented.
• Establishing clear criteria for completion, so teams know when a task is truly done.

Furthermore, spec-driven development introduces a "gated" workflow. Each step in the process must be validated by a human reviewer before moving on to the next phase. This iterative feedback loop ensures that mistakes or misalignments are detected early, not after hours of wasted effort.

How to Use Spec-Driven Development

The workflow for spec-driven development is divided into four distinct phases. Each phase must be fully validated and approved before proceeding:

1. Specify

   • Begin by writing a high-level vision for the project, feature, or change.
   • Ask clarifying questions to the human stakeholder until all requirements are explicit.
   • Before documenting requirements, list all assumptions you are making.
   • Example:
     plaintext

     ASSUMPTIONS I'M MAKING:
     1. This feature is intended for authenticated users only.
     2. The API endpoint already exists.

   • Once assumptions are surfaced and requirements are clarified, document the detailed specification. This should include goals, non-goals, acceptance criteria, and any open questions.

2. Plan

   • Break down the specification into a concrete plan.
   • Identify which modules, components, or files will be affected.
   • Outline the approach, architecture, and any major decisions.
   • Example:
     markdown

     Plan:
     - Update UserProfile component to support dark mode.
     - Refactor ThemeContext to allow dynamic theme switching.
     - Add unit tests for new theme logic.

3. Tasks

   • Translate the plan into a checklist of actionable tasks.
   • Each task should be small and discrete enough for clear progress tracking.
   • Example:
     plaintext

     [ ] Add dark mode toggle to settings page
     [ ] Update ThemeContext logic
     [ ] Write unit tests for theme switching
     [ ] Update documentation

4. Implement

   • Only after the above phases have been approved do you write and commit code.
   • Each code change should be mapped back to a specific task and requirement.

At every phase, human review is mandatory. Do not skip steps or proceed without explicit approval. This process prevents misalignment and ensures the implementation matches the specification.

When to Use Spec-Driven Development

Use spec-driven development in the following scenarios:

• When starting a new project or feature.
• When requirements are ambiguous, incomplete, or only exist as a vague idea.
• When making changes that affect multiple files, modules, or architectural layers.
• When preparing to make significant architectural decisions.
• When a task would take more than 30 minutes to implement.

Do not use this process for trivial changes such as typo corrections, single-line fixes, or modifications where the requirements are simple and self-contained.

Important Notes

• Specification before code: Never write code before the specification is complete and reviewed.
• Surface assumptions early: Listing your assumptions before drafting the spec avoids misunderstandings later.
• Gated process: Each phase (Specify, Plan, Tasks, Implement) requires explicit human review and approval before proceeding.
• Review and feedback: The process is designed for iterative feedback. Encourage stakeholders to challenge and clarify requirements during the Specify phase.
• Documentation: All specs, plans, and tasks should be documented and easily accessible for future reference.
• Be concise but thorough: Specifications should be detailed enough to remove ambiguity but concise enough to be actionable.

Spec-driven development transforms software engineering from guesswork into a structured, collaborative process. By following this skill, teams can build software with greater confidence, fewer surprises, and higher quality outcomes.