Section 1
Foundations
From Vibe-Coding to Structured Specs — the mindset shift, historical lineage, and core practices of Spec-Driven Development.
"What does the spec say should happen — not what does the code happen to do.
Overview
Section 1 establishes the foundational mindset shift from vibe-coding (prompting AI and hoping for the best) to AI engineering (directing AI with clear, executable specifications). The goal is alignment, traceability, and predictable outcomes — not faster guessing.
When spec and code diverge, the spec wins — you fix the code, not rewrite the intent to match accidents.
Historical Lineage
SDLC → PRDs → TDD → BDD → SDD. Each era solved part of the alignment problem. SDD composes them for the AI era.
2020s–
Spec-Driven Development
Can the spec itself drive AI to build it?
What it solved
Vibe-coding — prompting AI without specs and accepting whatever code "happens" to emerge.
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 clear question, artifact, and output. Never skip ahead: spec before plan, plan before tasks, tasks before code.
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.
Artifact
requirements.md · shaped specAnti-pattern
Skipping straight to prompts — vibe-coding without a spec
Outputs
- User stories with success criteria
- Acceptance criteria and data contracts
- Zero open items (Clarification Gate passed)
Specification → Plan → Tasks → Code → VerifyCore Concepts
shape-spec
Structured conversations before code. Clarify requirements — no assumptions.
Clarification Gate
Zero unresolved items in requirements.md before implementation begins.
Version-Controlled Specs
requirements.md lives in the repo — the system of record, not chat logs.
Executable Intent
Specs generate tasks, plans, and AI prompts — not wishes.
User Stories
Goals over implementation. Success criteria define done objectively.
User Story Example
Bad: As a user, I want a React modal with a form so that I can submit data.
Good: As a learner, I want to capture section notes in a structured format so that I can revisit concepts without searching chat history.
Workflow
- 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
Gate condition: open items = 0 → then generate tasks & implement
Key Terms
| Term | Definition |
|---|---|
| SDLC | Software Development Life Cycle — phased process from requirements to maintenance |
| PRD | Product Requirements Document — structured description of what to build and why |
| TDD | Test-Driven Development — write failing tests first, then code to pass them |
| BDD | Behavior-Driven Development — given/when/then scenarios as executable specs |
| SDD | Spec-Driven Development — version-controlled, executable specs for AI and humans |
| Vibe-coding | Prompting AI without structured specs; outcomes depend on luck |
| AI Engineering | Directing AI with clear, executable specifications for predictable results |
| shape-spec | Structured conversation process to clarify feature requirements |
| Clarification Gate | Blocker requiring zero open items before implementation |
| Executable intent | Specs detailed enough to auto-generate tasks, plans, and prompts |
| Living document | A spec that evolves with the project, tracked in version control |
| Development stages | Specification → Plan → Tasks → Code → Verify — the ordered pipeline from intent to verified software |
Practical Takeaways
- 1Spec over code. Ask what the spec says should happen — not what the code happens to do.
- 2SDD stands on shoulders. SDLC, PRDs, TDD, and BDD each solved part of the problem — SDD composes them for the AI era.
- 3Never skip shaping. A 15-minute spec conversation saves hours of rework.
- 4Specs live in the repo. If it is not in git, it does not exist.
- 5Open items are stop signs. Resolve them before coding.
- 6Write for execution. If AI cannot generate a task from your spec, rewrite it.
- 7Stories describe goals. Let implementation emerge from clear intent.
- 8Follow the stages. Specification → Plan → Tasks → Code → Verify — never skip ahead.
Next: shape-spec workflow
Structured feature shaping checklist and phases.