Why Spec Driven Development

Why Spec-Driven Development

Spec-Driven Development exists to fix a specific, recurring failure mode: the gap between what a team intended to build and what the code actually does. This page explains the problems SDD targets, why they matter more now, and the trade-offs to go in with eyes open.

The problem SDD addresses

In most projects the real specification is scattered and perishable:

• A ticket says "build an episodes page" with three bullet points.
• The actual design lives in a Word doc, a Figma comment, or someone's head.
• By the time code ships, the ticket, the doc, and the code have all drifted.
• Six months later nobody can say why a decision was made, only that the code does what it does.

Code is an excellent description of how. It is a poor description of what and a terrible description of why. SDD restores the missing layers and keeps them next to the code, under version control, where they cannot quietly rot.

Why it matters more now

AI coding agents changed the economics. An agent can generate a plausible implementation in minutes, but it will faithfully build the wrong thing if the intent is vague. The bottleneck moved:

The scarce resource is no longer typing code. It is a precise, agreed, machine-readable statement of intent.

SDD leans into this. A clear spec plus a constitution gives the agent the two things it needs: a target to hit and guardrails it must not cross. The human spends their effort where it has the most leverage — on intent and review — instead of on boilerplate.

What you get

Benefit	How SDD delivers it
Intent is explicit	spec.md states user stories, requirements, and success criteria in testable language
Decisions are durable	research.md and plan.md record why, versioned with the code
Guardrails are enforced	The constitution is checked at planning time, not hoped for
Work is decomposable	tasks.md turns the plan into small, independently testable slices
Reviews are holistic	A PR can change spec, plan, and code together and be reviewed as one unit
Onboarding is faster	A newcomer reads the spec and plan instead of reverse-engineering the code
AI is steerable	The agent expands intent into a plan and tasks while the human controls direction

A concrete example from this repo

The spec says the featured episode must be one of the 20 episodes and marked as featured, not a twenty-first entry. That single sentence:

1. Removed an ambiguity that would otherwise surface as a bug.
2. Became a functional requirement (FR-017) and a success criterion.
3. Became a content-contract test that asserts exactly one featured episode within the catalog of twenty.
4. Constrained the data model and the implementation.

The intent flowed cleanly from spec to test to code, and the test now protects that intent against future regressions. That traceability is the whole point.

Honest trade-offs

SDD is not free and it is not always the right tool:

• Up-front effort. Writing a spec and plan feels slower than diving into code. The payoff comes later, in reduced rework and drift.
• Ceremony for tiny changes. A one-line typo fix does not need a spec. Match the process weight to the change.
• It is newer. Tooling and conventions are still maturing compared to decades-old Agile and Azure DevOps practice.
• It is not portfolio planning. SDD describes and builds a feature well. It does not replace the cross-team coordination, reporting, and release planning that tools like Azure Boards provide. See Methodology Comparison for how they fit together.

When to reach for SDD

• New features where intent deserves to be captured durably.
• Greenfield projects where you want the architecture decisions recorded.
• Any work where an AI agent will do significant implementation and needs a precise target plus guardrails.

For how SDD sits alongside classic Azure DevOps work-item planning and the HVE-core Research-Plan-Implement loop, continue to Methodology Comparison.