Spec-DrivenDevelopment
From vibe-coding to AI engineering — scroll through an immersive journey where structured specs turn AI speed into predictable outcomes.
What does the spec say should happen — not what does the code happen to do.
01
Understand
shape-spec & requirements
02
Plan
Clarification Gate passes
03
Build
Tasks → implement → verify
Two paths. One choice.
Click each path to see how intent flows — or drifts — through the process.
Slower start. Predictable delivery. Intent in the repo.
Historical Lineage
SDLC → PRDs → TDD → BDD → SDD. Scroll to travel through each era — SDD composes them for the AI age.
1960s–
Software Development Life Cycle
Chaos. Projects had no repeatable process — deadlines slipped and scope ballooned.
Core question
What process should we follow?
SDD inherits
Phased thinking — understand before you build. The Clarification Gate is SDLC's requirements phase, enforced.
1990s–
Product Requirements Document
The "telephone game" between product, design, and engineering.
Core question
What should the product do?
SDD inherits
Structured intent — problem, users, scope, success criteria — inside version control.
1990s–
Test-Driven Development
"Does the code do what we think?" Tests became executable specifications at the unit level.
Core question
Does the code behave correctly?
SDD inherits
Specs should be executable — SDD extends this from unit tests to tasks, plans, and AI prompts.
2000s–
Behavior-Driven Development
TDD's tests were too technical. BDD made specs readable by product owners while automatable.
Core question
Does it behave correctly for the user?
SDD inherits
User-facing language, acceptance criteria, and scenarios — living in requirements.md.
2020s–
Spec-Driven Development
Vibe-coding — prompting AI without specs and accepting whatever code "happens" to emerge.
Core question
Can the spec itself drive AI to build it?
SDD inherits
Composes SDLC, PRD, TDD, and BDD for the AI era — specs in repo, gate enforced, intent executable.
Development Stages
From intent to verified software. Each stage has a question, artifact, and output — never skip ahead.
Stage 1
Specification
Capture intent before any implementation. Use shape-spec to clarify requirements, write user stories, define acceptance criteria, and resolve all open items through the Clarification Gate.
Question
What must be built?
Artifact
requirements.md · shaped spec
Anti-pattern
Skipping straight to prompts — vibe-coding without a spec
Stage 2
Plan
Translate the approved spec into a structured plan. Define milestones, dependencies, technical approach, and the order of work — still without writing feature code.
Question
How will we build it?
Artifact
Project plan · architecture notes
Anti-pattern
Planning in your head or in chat — not version-controlled
Stage 3
Tasks
Break the plan into small, actionable, ordered tasks. Each task should trace back to a user story or acceptance criterion — executable enough for AI or a developer to pick up and run.
Question
What are the concrete steps?
Artifact
Task list · AI prompts
Anti-pattern
Vague tasks like 'build the feature' with no spec link
Stage 4
Code
Implement against the spec and tasks — not against vibes. Code is the output of clear intent, not the source of truth. When code and spec diverge, fix the code.
Question
Build it — does it match the spec?
Artifact
Source code in repo
Anti-pattern
Accepting whatever AI generates and retro-fitting the spec
Stage 5
Verify
Validate against the spec — not against what the code happens to do. Run acceptance criteria, behaviour checks, and review open items are still resolved.
Question
Does it match what the spec says should happen?
Artifact
Tests · acceptance checks
Anti-pattern
'Looks good to me' without running criteria
SDD Learning Path — 3D Journey
Drag to orbit · Click nodes to explore · Follow the path from shape-spec to verify
Core Concepts
Hover to explore — each practice turns vibe-coding into AI engineering.
SDD Workflow
The path from feature idea to verified implementation.
- 1
Feature idea
A need emerges
- 2
shape-spec
Structured conversation — clarify, don't assume
- 3
requirements.md
Living doc — stories, criteria, open items
- 4
Clarification Gate
Open items = 0?
- 5
Generate & implement
Tasks, plans, prompts, code