Spec-Driven Development: Let the Specification Drive the Code

Spec-Driven Development is a new approach to coding where the specification comes first, followed by the code. Traditionally, code is written first and then documented, but this method can lead to confusion and make it difficult to review the generated code. With the help of AI, code generation has become faster, but the review process remains manual and tedious.

Spec-Driven Development aims to solve this issue by reversing the traditional order of development, starting with the intent and then creating a specification that becomes the source of truth.

The main advantage of Spec-Driven Development is that it helps prevent the creation of code that nobody understands, as the specification serves as a clear guide for the development process. By making the intent and specifications version-controlled alongside the code, any divergence between the specification and the code can be easily identified and resolved. This approach also allows for easier maintenance, as business rules, auditing, and compliance requirements can be traced back to the specification.

The Spec-Driven Development process consists of six phases:

1. Constitution: This file outlines the rules that apply to the entire project, including the stack, architecture patterns, and quality standards. It serves as the foundation for the project and is referenced by all other specifications.

2. Specification: This file contains the "what" and "why" of the project, including the business objective, functional requirements, users, edge cases, and what's out of scope. Technical terms should not appear in this file.

3. Clarification: In this phase, the specification is reviewed for ambiguities and clarifications are made. This phase involves asking the AI to point out any unclear parts and ensuring that all blind spots are addressed. It is the first human gate in the process.

4. Plan: This file outlines the technical details of the project, including the architecture, HTTP contracts, data model, decisions, and risks. Technical terms are allowed in this file.

5. Tasks: This file contains atomic, ordered units of work, each with an ID, origin, dependency, and completion criteria. This file allows for easy review and verification of the tasks.

6. Analysis: This file contains a report that cross-checks the specification, plan, and tasks, ensuring that there are no inconsistencies or gaps.

Each phase produces a file, and the order of the phases remains the same, regardless of the urgency of the project. The implementation phase involves executing tasks one at a time, with a focused prompt that references the relevant specification, plan, and analysis report. If the result does not meet the expectations, the process is rerun from the specification phase, ensuring that the code always aligns with the intent.