Stop Letting AI Write Code Directly—Learn Spec‑Driven Development (SDD)

What Is Spec‑Driven Development (SDD)?

SDD (Spec‑Driven Development) means creating a detailed specification document that captures the goal, scope, system behavior, design constraints, and task breakdown of a change before any code is written. AI then follows this stable engineering context, reducing guesswork, accidental changes to legacy logic, and deviation from intended implementation.

Common SDD Frameworks

Several frameworks support AI‑assisted SDD:

GitHub Spec Kit : Ideal for new projects; turns specifications into an executable development entry point.

Kiro Specs : Integrated into AI IDEs, organizing requirements.md, design.md, and tasks.md.

Tessl : Aggressive “spec‑as‑source” approach where code is generated directly from specs.

OpenSpec : Focuses on managing incremental changes in existing projects, preserving traceable engineering context.

The emphasis of each tool differs; OpenSpec is preferred for modifying existing systems, while GitHub Spec Kit suits greenfield projects.

OpenSpec‑Based SDD Workflow Example

OpenSpec’s core flow is explore → propose → apply → archive :

Explore : AI analyzes the current system to understand theme mechanisms, state management, page scope, and compatibility requirements.

Propose : The analysis results are turned into structured documents (proposal.md, specs/, design.md, tasks.md) rather than code.

Apply : AI implements code based on tasks.md; it consults design.md for technical details and specs/ for behavior boundaries.

Archive : After implementation and testing, all specification documents are stored as team assets for future reference.

For example, when implementing a dark‑mode feature, a direct AI prompt would make many assumptions (where to store theme state, system‑theme sync, legacy configuration handling). By first exploring, those assumptions are clarified, preventing mismatches.

SDD vs. TDD

Test‑Driven Development (TDD) starts with writing tests before code, using test results as feedback. SDD precedes implementation even earlier by defining requirements, system behavior, boundaries, design constraints, and task breakdown before any code is written.

When to Use SDD

SDD is suitable for:

Feature iterations in existing projects where preserving historical logic is critical.

Cross‑module changes affecting front‑end, back‑end, databases, or permissions.

Requirements that are likely to evolve and need a documented decision trail.

Team collaboration where humans and AI must agree on the same specification.

SDD is not recommended for trivial tasks such as one‑off scripts, simple modifications with clear boundaries, or low‑cost implementations where the overhead outweighs benefits.