Most projects accumulate sources of truth — wikis, tickets, READMEs, code comments, ADRs. Each one is authoritative in its own corner. Each one drifts. Eventually the documentation stops describing the system, and engineers read the code instead.

Spec Driven Development is a response to that drift.

What follows is one version of SDD — the one I run. The core idea (spec as source of truth, code derived from it) is shared across the field; specifics like the spec format, the lifecycle, and the pipeline phases are choices, not consensus.

What SDD Is Not

It is not a PRD. Product Requirements Documents describe intent from a business perspective. They are written before development begins and rarely updated once work starts. By the time a feature ships, the PRD typically bears little resemblance to what was built. SDD specifications are living documents — they evolve with the system and remain accurate after the code is written, not just before.

It is not Agile or Scrum. Agile is a philosophy about how teams collaborate and iterate. Scrum is a framework for organizing that work into sprints, ceremonies, and roles. Both come with their own artifacts — backlogs, user stories, increments — but those artifacts coordinate work and track deliverables; they do not establish a durable description of what the system does. SDD is not a replacement for how your team organizes work — it is a discipline about what your source of truth is.

It is not vibe coding. Vibe coding — using AI to generate code from loose natural language prompts — optimizes for speed of initial output at the expense of consistency, maintainability, and predictability. It works for prototypes. It breaks down for production systems where multiple people, and multiple AI agents, need to work on the same codebase over time without introducing drift.

It is not just using AI coding agents. AI coding agents are tools. SDD is the discipline that makes those tools reliable. An AI agent given a well-structured spec produces consistent, predictable output. An AI agent given a vague prompt produces code that may work today and silently break something tomorrow.

What SDD Actually Is

Spec Driven Development is a methodology in which the specification is the primary artifact — the source of truth from which everything else is derived. Code is an output of the spec, not the other way around.

This is a meaningful inversion. In most teams, the code is what’s real. Documentation is written to describe code that already exists, which means it is always slightly out of date, always slightly wrong, and rarely trusted. In SDD, the spec is what’s real. Code that diverges from the spec is wrong by definition.

A spec is a precise, readable description of what a feature does — written at a level of abstraction that an engineer, a product manager, and a future maintainer can all understand. It describes behavior, not implementation. It answers the question what should the system do without prescribing how the system should do it.

In practice, a spec is a markdown file. Frontmatter at the top carries metadata — the spec’s lifecycle status, its dependencies on other specs, and any tags that classify it. The body describes the feature itself.

In skeleton form:

---
title: "{NNN-feature-name} — spec"
status: draft
dependencies: []
tags: []
---

# Feature Name

Brief description of what the feature does.

## {Section}

Free-form sections describing behavior, contracts, and constraints. Use as many as the feature warrants.

## Acceptance Criteria

Concrete, testable conditions that define done.

- [ ] ...

## Open Questions

Uncertainties still being worked through.

- ...

## Resolved Questions

Answered questions, preserved with their reasoning.

- ...

Acceptance Criteria and Open Questions are the required sections. The rest are free-form — use as many headings as the feature warrants and whatever names make sense (behavior, data model, edge cases, configuration, integration notes). The discipline is not that every spec is short; it is that every section earns its place. The result is a single coherent document — version-controlled, navigable, and the authoritative source for the feature it describes.

The Pipeline

A spec is the primary artifact, not the only one. Every feature flows through the same sequence:

spec → plan → tasks → implement

The spec defines what the system does. The plan defines how — technical decisions, affected files, trade-offs. Tasks decompose the plan into discrete, ordered work items. Implementation writes the code, guided by the plan and following the task list.

Each phase produces an artifact the next phase consumes. No code is written without a spec. No implementation begins without a plan. When implementation is derived from a plan derived from a spec, drift between code and spec becomes structurally hard rather than structurally inevitable.

The spec carries a status as it moves — draft → clarified → planned → in-progress → done — so anyone reading the repository can tell at a glance which features are designed, which are being built, and which are shipped. The spec is alive: it changes as the feature is refined, and its status reflects where the work is.

The Spec as Source of Truth

The power of this approach compounds over time. When a new engineer joins the team, they read the specs — not the tickets, not the wiki, not the code comments. When a bug surfaces, the first question is whether the spec covers the scenario — not who filed the ticket or which sprint it belongs to. When an AI agent is asked to implement a feature or fix an issue, it is given the spec as context — not a vague description typed into a chat window.

Specs live in version control alongside the code. Changes to behavior require changes to the spec. A pull request that modifies behavior without updating the spec is incomplete by definition. This is how the spec stays alive rather than rotting into documentation debt.

Where This Series Goes

The next post tackles the question every team hits immediately after adopting SDD: where do bugs go? The answer reframes what a bug actually is — and leads to a workflow that is leaner than most processes can offer.

The post after that introduces govern — an open-source toolkit that operationalizes SDD as a set of slash commands inside an AI coding agent. Once govern is on the table, the rest of the series uses it as the working example, because the methodology is sharpest when you can see the artifacts it produces.

Reliable software comes from teams that agree on what the system should do before anyone talks about how it works. Spec Driven Development is the discipline that makes that agreement stick.