Methodology Overview
Relevant source files
The following files were used as context for generating this wiki page:Spec-driven development is a systematic approach to software feature development that emphasizes thorough planning, clear documentation, and structured implementation. This methodology transforms rough feature ideas into well-defined, implementable solutions through a structured process. The core philosophy is "Clarity Before Code," ensuring that a clear understanding of requirements and a well-thought-out design precede any implementation effort. This reduces ambiguity, minimizes rework, and increases the likelihood of building the right solution correctly.
Sources: spec-process-guide/methodology/overview.md:13-16, spec-process-guide/methodology/philosophy.md:15-20
The methodology is designed to be iterative, encouraging refinement and validation at each step rather than a rigid linear progression. It serves as a powerful communication tool, aligning stakeholders and preserving decision rationale for future maintenance. It is particularly effective when used with AI-assisted development tools, as the structured inputs provide the necessary context for AI systems to be effective collaborators.
Sources: spec-process-guide/methodology/philosophy.md:22-34, spec-process-guide/methodology/philosophy.md:70-75
The Three-Phase Approach
The spec-driven development process is structured into a three-phase workflow: Requirements, Design, and Tasks. Each phase builds upon the previous one, with approval gates to ensure quality and alignment before proceeding. This separation allows developers to focus on one type of thinking at a time (requirements, design, or implementation), reducing cognitive load and improving decision quality.
Sources: spec-process-guide/methodology/overview.md:18-20, spec-process-guide/methodology/philosophy.md:60-67
This diagram illustrates the iterative, three-phase workflow of spec-driven development.
Phase 1: Requirements Gathering
Purpose: To transform vague feature ideas into clear, testable requirements. This phase ensures all stakeholders have a shared understanding of what is being built and provides clear success criteria.
Sources: spec-process-guide/methodology/overview.md:23-25, skills/spec-driven-development/SKILL.md:21-22
Key Activities:
- Capture user stories that express value and purpose.
- Define acceptance criteria using EARS (Easy Approach to Requirements Syntax).
- Identify edge cases, constraints, and non-functional requirements.
- Validate the completeness and feasibility of the requirements with stakeholders.
Sources: spec-process-guide/methodology/overview.md:26-30, skills/spec-driven-development/SKILL.md:24-27
A key standard in this phase is the use of EARS (Easy Approach to Requirements Syntax), a structured method for writing unambiguous requirements.
Sources: spec-process-guide/resources/standards.md:13-14
| EARS Keyword | Format | Description |
|---|---|---|
| WHEN | WHEN [event] THEN [system] SHALL [response] | Used for requirements triggered by specific events. |
| IF | IF [condition] THEN [system] SHALL [response] | Used for requirements that depend on a specific system state. |
| WHILE | WHILE [condition] [system] SHALL [continuous behavior] | Used for requirements that must be maintained during an ongoing operation. |
| WHERE | WHERE [context] [system] SHALL [behavior] | Used for requirements that apply only in specific contexts, like on a mobile device. |
Sources: spec-process-guide/resources/standards.md:18-48, skills/spec-driven-development/SKILL.md:29-33
Phase 2: Design Documentation
Purpose: To create a comprehensive technical blueprint for implementation based on the approved requirements. This phase identifies technical challenges before coding begins and documents key architectural decisions.
Sources: spec-process-guide/methodology/overview.md:38-40, skills/design-documentation/SKILL.md:11-15
Key Activities:
- Research technical approaches, constraints, and third-party integrations.
- Define the system architecture, component interactions, and data flows.
- Specify data models, interfaces, and API contracts.
- Plan for error handling, security, and testing strategies.
- Document key design decisions and their rationale.
Sources: spec-process-guide/methodology/overview.md:41-45, spec-process-guide/process/design-phase.md:21-33
The design document typically includes diagrams to visualize the system structure. The following diagram shows a sample high-level architecture.
Phase 3: Task Planning
Purpose: To break down the detailed design into a sequence of actionable, manageable implementation steps. This decomposition makes large features easier to track and enables parallel work.
Sources: spec-process-guide/methodology/overview.md:53-55, skills/spec-driven-development/SKILL.md:83-84
Key Activities:
- Convert design components into specific, small coding tasks (e.g., 2-4 hours each).
- Sequence tasks to respect dependencies and enable incremental progress.
- Define clear objectives and completion criteria for each task.
- Reference the requirements and design elements to ensure traceability.
Sources: spec-process-guide/methodology/overview.md:56-60, skills/spec-driven-development/SKILL.md:86-89, skills/spec-driven-development/SKILL.md:109
Benefits of Spec-Driven Development
Adopting this methodology provides several key advantages for development teams.
| Benefit | Description |
|---|---|
| Reduced Risk and Uncertainty | Thorough upfront planning helps identify and address issues early, reducing the risk of building the wrong solution or facing unexpected technical hurdles. |
| Improved Quality and Maintainability | The focus on clear requirements and thoughtful design leads to more robust, well-tested, and maintainable code. |
| Enhanced Collaboration | Specs act as a common language, creating a shared understanding among team members, stakeholders, and future maintainers. |
| Better Estimation and Planning | Detailed planning enables more accurate time and resource estimations, leading to better project management. |
| Knowledge Preservation | Specs serve as living documentation that preserves the "why" behind design decisions and implementation approaches for the long term. |
| Improved AI Collaboration | The structured, clear inputs generated by the process provide the context that AI assistants need to produce high-quality, relevant outputs. |
Sources: spec-process-guide/methodology/overview.md:62-83, spec-process-guide/methodology/philosophy.md:70-75
When to Use This Methodology
Spec-driven development is highly effective but not universally required for every task. It is designed to complement other methodologies like Agile, not replace them.
Sources: spec-process-guide/methodology/overview.md:99-100, spec-process-guide/methodology/philosophy.md:48-50
| Ideal Scenarios | Less Suitable Scenarios |
|---|---|
| Complex features with multiple components or integrations. | Simple, well-understood bug fixes. |
| High-stakes projects where the cost of rework is significant. | Experimental prototypes where rapid iteration is the goal. |
| Projects requiring collaboration between multiple developers. | Time-critical hotfixes that require immediate action. |
| Features where knowledge preservation is important. | Implementation of standard, repetitive functionality. |
| AI-assisted development workflows. |
Sources: spec-process-guide/methodology/overview.md:87-97, skills/spec-driven-development/SKILL.md:12-20
Comparison with Other Methodologies
This methodology shares principles with other development practices but has key distinctions.
| Methodology | Similarities | Key Differences |
|---|---|---|
| Waterfall | Emphasizes upfront planning and a sequential approach. | More iterative within each phase; specs are living documents optimized for feature-level work. |
| Agile | Values iterative refinement and feedback. | Places greater emphasis on upfront design and structured documentation; designed to work within Agile sprints for larger stories. |
| Test-Driven Development (TDD) | Defines success criteria before implementation; uses an iterative cycle. | Operates at a higher level of abstraction, including business requirements and system design, not just test cases. |
| Design-First Development | Prioritizes design and technical specifications before coding. | Includes an explicit requirements gathering phase and a more structured approach to task breakdown. |
Sources: spec-process-guide/methodology/philosophy.md:36-58
Conclusion
The philosophy of spec-driven development is centered on the belief that thoughtful planning and clear communication lead to better software. By separating development into distinct phases of requirements, design, and tasks, teams can manage cognitive load, detect problems earlier, and collaborate more effectively. This structured approach is especially powerful when paired with AI development tools, providing the clarity and context needed for successful AI-human collaboration.
Sources: spec-process-guide/methodology/philosophy.md:88-94