Skip to main content

SDD (Specification-Driven Development)

Think of it as building from blueprints instead of verbal instructions. A contractor given detailed architectural drawings — room dimensions, materials, load-bearing requirements, plumbing routes — produces predictable, inspectable results. Give them a vague description ("make it look nice") and every decision becomes a guess. Specification-Driven Development applies this principle to AI: instead of giving an agent vague instructions and hoping for the best, you provide structured specifications that define exactly what success looks like, and the agent's output is validated against those specifications.

Prerequisites​

Before reading this page, make sure you're familiar with:

  • Agents — software that uses an LLM to observe, reason, and act toward a goal
  • Agentic Workflows — multi-step flows where agents plan, execute, and verify tasks
  • Skills — modular capability packages that give agents domain-specific knowledge

How It Works​

The diagram shows the four-stage SDD cycle. First, a specification defines the contract — inputs the agent will receive, outputs it must produce, constraints it must respect, and criteria for validation. This isn't a casual prompt; it's a structured document with verifiable requirements.

The AI agent receives the specification and executes against it. Unlike ad-hoc prompting where the agent interprets vague instructions, SDD gives the agent a concrete contract. It knows exactly what files to create, what patterns to follow, and what acceptance criteria to meet. Ambiguity is eliminated before work begins — the agent doesn't guess what you want because the specification tells it.

The agent's output — code, documentation, configuration — goes through validation. Validation checks whether the output satisfies the specification's success criteria. Do the files exist? Do they contain the required patterns? Do the tests pass? Does the structure match the contract? Validation can be automated (grep checks, test suites, build commands) or manual (human review against defined criteria).

If validation fails, the specification provides the feedback loop. The agent receives specific information about which criteria weren't met and iterates. The specification doesn't change — the implementation adapts until it satisfies the contract. This transforms working with AI from subjective ("does it look right?") to objective ("does it meet the spec?").

Why It Matters​

SDD solves the fundamental reliability problem in AI-assisted development. Without specifications, agents produce work that looks plausible but may miss requirements, introduce subtle bugs, or drift from the intended design. With SDD, every piece of work has a definition of done that can be mechanically verified.

This matters most in agentic workflows where multiple agents collaborate. If each agent follows its own interpretation of vague instructions, integration breaks down. SDD ensures agents agree on contracts — one agent's output specification matches the next agent's input specification. Agents work independently on parallel tasks and their outputs compose correctly because they all built against the same specifications.

SDD principles apply in practice when specifications are treated as planning artifacts, acceptance criteria serve as validation contracts, and verification acts as proof of compliance.