Spec Driven Development Part 1: Overview

AI coding agents can now write hundreds of lines of code in seconds. But this speed has a dark side: the faster an agent produces code, the faster wrong-direction code gets produced too. The problem isn’t the model’s ability — the problem is the way we communicate with that agent. Spec-Driven Development (SDD) was born as the answer to this problem: the discipline of writing structured specifications as the primary source of truth, before a single line of code is generated. This article is the opener of the Spec Driven Development series, discussing why this approach is relevant now, how it differs from older methodologies like TDD and BDD, and what the big picture of its workflow looks like.

The Problem with “Vibe Coding”

The term “vibe coding” — coding based only on short instructions and intuition, without clear specifications — became popular as AI coding assistants went mainstream. The method is simple: you type a prompt, the agent produces code, you try to run it, if it’s wrong you prompt again. This loop feels productive at first, especially for small prototypes. But as project complexity rises, vibe coding starts showing its cracks.

There are three symptoms that almost always appear:

Output can’t be verified. Without explicit acceptance criteria, there’s no objective way to assess whether the code the agent produced is truly “done” or just looks done. Reviews become long because reviewers have to guess what was actually requested.

Drift from the original intent. The agent produces plausible code — looks reasonable, passes compilation, even passes simple tests — but silently solves a different problem than intended. This drift is often only discovered during code review or, worse, when it’s already in production.

Context is lost between sessions. Agents are stateless. Once the context window fills or a new session starts, all architectural decisions, the reasoning behind an approach, and implicit agreements are lost. Developers have to repeat explanations from scratch, and the next agent might make decisions contradicting the previous one.

Research shows that LLMs can produce code with security vulnerabilities at a fairly significant rate depending on the benchmark used — not a rare case, but a consistent pattern that appears when security specifications aren’t stated explicitly. The root cause is always the same: AI doesn’t lack ability, it lacks clarity about what’s actually being asked.

• Vibe coding isn’t the enemy — for quick prototypes or throwaway scripts, it’s actually the right approach
• Problems appear when vibe coding is used for code that must survive in production and be maintained long-term
• The larger the codebase and the more people (or agents) involved, the more expensive ambiguity becomes

What Is Spec-Driven Development

Spec-Driven Development is a methodology where the specification — not the code — becomes the main artifact and source of truth of the software development process. Code becomes output that can be regenerated from the spec, whether by humans, AI agents, or a combination of both. This spec isn’t passive documentation written after a feature is finished, but a living document that precedes the implementation and is used to validate its results.

The difference from traditional documentation lies in its “executable” nature. Traditional specs are read by humans then forgotten once the code is done. Specs in SDD are designed to be executable as a validation gate — the agent reads the spec to produce code, then the same spec is used to verify whether the result matches.

A good spec usually contains four core elements:

These elements will be discussed in more detail in Part 2 of this series. For now, what matters is understanding the mindset shift: from “I ask AI to make X” to “I define what X is precisely, then AI executes it”.

Spec-Driven vs TDD vs BDD

SDD is often misunderstood as TDD or BDD with a new name. The three do share the same spirit — determining “correct” before writing code — but they differ in which artifact is considered canonical.

SDD doesn’t replace TDD or BDD — SDD actually accommodates both. Acceptance criteria in a spec are essentially BDD scenarios in a stricter format, and a good SDD workflow still produces unit tests and integration tests as part of its output. The difference is that those tests are derived from the spec, not manually written first with the spec following afterward.

What makes SDD specifically relevant in recent years is the emergence of AI coding agents capable of autonomously executing complex instructions. TDD and BDD were designed for coordination between humans. SDD is designed for coordination between humans and agents — where language precision is far more crucial because agents don’t have the implicit context that human coworkers have.

The Anatomy of the Spec-Driven Workflow

Almost all SDD frameworks in existence today — whether open source or built into various AI coding tools — converge on the same four-phase loop pattern:

flowchart TD
    A[Write Spec] --> B[Review & Refine Spec]
    B --> C[Generate Plan & Task]
    C --> D[Agent Implementation]
    D --> E[Verify against Spec]
    E -- Matches --> F[Merge / Done]
    E -- Doesn't match --> G[Identify Gap]
    G --> B

Write Spec — The developer (or an agent under developer supervision) writes a spec containing intent, constraints, and acceptance criteria. This is the most important phase because the entire accuracy of the final result depends on the clarity of this stage.

Review & Refine — The spec is reviewed before execution begins. Ambiguities, contradictions, or missing requirements are fixed at this stage — far cheaper than fixing them after code has been written.

Generate Plan & Task — The spec is translated into an architectural plan and broken into small individually executable tasks. This decomposition matters so the agent doesn’t try to complete the entire feature in one big step that’s hard to verify.

Implementation — The agent (or developer) executes tasks according to the plan, with the spec as the constraint reference throughout the process.

Verification — The output is checked against the acceptance criteria in the spec. Ideally this process is partially automated (tests, linters, type-checks) and partially involves human review, especially for architectural decisions.

If verification fails, the loop returns to the refine phase — not directly “re-prompting” like in vibe coding. This is the structural difference making SDD more predictable: failure is treated as a signal that the spec or plan needs improvement, not just thrown back at the agent to try again hoping for a different result.

This loop will be the reference framework for all subsequent articles in this series. Each phase — writing specs, composing acceptance criteria, translating to tasks, up to verification — will be discussed in depth one by one.

When Spec-Driven Development Matters

SDD isn’t an approach that must be used for everything. Writing a complete spec for a one-line change is clearly excessive. There’s a simple trigger that can be used to decide: if you’ll be disappointed when the agent interprets the requirement differently from what you meant, write a spec. If a wrong result can still be fixed with one follow-up prompt, just prompt directly without a spec.

Several contexts where SDD clearly provides value:

• Features with many edge cases — the more special conditions to handle, the greater the risk of the agent missing one without an explicit spec
• Team or multi-agent work — when more than one person or agent touches the same codebase, a spec becomes a shared contract preventing divergent conventions
• Security or compliance requirements — constraints that must not be violated need to be stated explicitly, not assumed the agent will “know by itself”
• Modernizing old codebases — specs help re-document systems whose original requirements are no longer clear
• Long-term projects — living specs help maintain context even as the developers and agents involved change over time

Conversely, for quick exploration, throwaway proof-of-concepts, or small fixes whose scope is clear from the start, the overhead of writing a spec usually isn’t worth the benefit.

Series Preview

This Part 1 only provides the big picture. The next four articles in the Spec Driven Development series will discuss each phase of the loop above in detail:

• Part 2 — The anatomy of a good spec: structure, mandatory elements, and examples of bad specs vs effective ones
• Part 3 — Specs for APIs and data contracts, including schemas as the source of truth
• Part 4 — The practical workflow from spec to code, including keeping the spec in sync with changes
• Part 5 — Testing in SDD: how acceptance criteria are derived into automated tests

After the Spec Driven Development series finishes, the discussion continues to a separate series on Agentic Development — how to design and control AI agents working more autonomously, with the spec as the foundation built in this series.

Summary

• Vibe coding is effective for quick prototypes, but fails to scale for production code because output is hard to verify and prone to drifting from the original intent
• Spec-Driven Development makes the specification — not the code — the primary source of truth that gets executed, not just passive documentation
• A good spec contains four core elements: intent, constraints, acceptance criteria, and non-goals
• SDD differs from TDD and BDD in scope: TDD focuses on tests, BDD focuses on behavior, SDD covers the entire cycle from requirements to documentation
• The SDD workflow follows a loop: write spec → review → generate plan → implementation → verification, with failures directed back to spec improvement, not just re-prompting
• Use a simple trigger to decide whether a spec is needed: if a wrong interpretation would bother you, write a spec; if one follow-up prompt can fix it, just go ahead
• SDD is most valuable for complex features, team/multi-agent work, security requirements, and long-term projects — not for quick exploration or small fixes