Skip to main content
Learn SDD here, and later put it to use with the Specathon.com Challenge.
Spec-Driven Development (SDD) is the opposite of vibe-coding. Instead of sending an AI agent on a scavenger hunt, you hand it a crystal-clear blueprint so the work lands right on the first pass. You treat the agent like a literal-minded teammate: the more detail you prep in advance, the less you have to bounce back and forth fixing guesses.

What is a spec?

A spec (short for specification) is a short document that spells out what to build, why it matters, and any guardrails to follow. Think of it as the instructions manual you give the agent before it writes a single line of code.

​
Why spec first?

Fewer loops

The spec carries every non-negotiable detail, so you avoid the endless clarify-rewrite-repeat cycle typical of casual prompting.

Reliable context

Upfront constraints keep the agent aligned with your patterns, integrations, and “do not touch” zones from the start.

Faster delivery

When the plan is locked before coding begins, implementation becomes execution instead of discovery.

​
How it differs from traditional prompting

Prompt ping-pong

  • Rough idea shared
  • Agent guesses the rest
  • Humans correct the guess
  • Context slowly drifts

SDD flow

  • Full spec written first
  • Agent follows the doc literally
  • Everyone shares one source of truth
  • Output matches expectations

​
The mini SDD loop

1

Plan the outcome

Write a short user story, the success criteria, and any taboo items (“do not rebuild auth”, “keep the CLI interface”).
2

Outline the build

Break the work into components, data flows, or API touches so the agent understands the architecture before writing code.
3

Package the brief

Feed the complete spec to the agent as the single instruction set, then let it implement without mid-prompt pivots.

​
A loose outline you can borrow

This outline is our go-to starting point—not a rulebook. Keep, remix, or skip sections so the spec fits your project.

Executive Summary

Open with a 3–5 sentence snapshot: who hurts today, why the change matters, and the win condition once it ships.

Core Insight

Highlight the single design idea guiding every other decision so reviewers grasp the throughline fast.

Current vs. Proposed Architecture

If you are extending a live system, add a quick “today” diagram, then sketch the future with pseudocode blocks or swimlanes.

Implementation Checklist

Break the work into RED/GREEN/VERIFY loops: tests you will add, code you will touch, and the command proving it passes.

Feature Completeness Check

Finish with a yes/no QA list tied to the promises in the spec so sign-off is objective.

​
When to reach for SDD

  • Legacy or regulated repos where surprises are expensive
  • Multi-system changes that span backend, frontend, and infra
  • Work that depends on existing patterns (naming, testing, telemetry)
  • Anytime “just wing it” would cause rework or risk
Think of SDD as storyboarding a movie scene before the cameras roll. The prep feels slower, but the actual shoot (and edit) goes way faster—especially when your co-star is an AI agent that thrives on precise direction.