SDStart Section 1
Interactive learning experienceSections 1–4 live

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

Scroll down & dive in

Two paths. One choice.

Click each path to see how intent flows — or drifts — through the process.

shape-spec
requirements.md
Gate
Tasks
Code
Verify

Slower start. Predictable delivery. Intent in the repo.

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.

Process phasesNot executableOutside repo

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.

Product documentPartially executableOutside repo

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.

Unit testsExecutableLives in repo

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.

Scenario filesExecutableLives in repo

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.

requirements.md + shaped specsExecutableLives in repoCurrent era

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

User stories with success criteriaAcceptance criteria and data contracts

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

Milestones and sequencingDependencies and risks identified

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

Ordered, checkbox-ready task listAI prompts derived from spec (not guesses)

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

Implementation committed to version controlEach change traceable to a task and story

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

All acceptance criteria checkedBehaviour matches spec intent