SDSection 2 →

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

Current era

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.

requirements.md + shaped specsExecutableLives in repo

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

What must be built?

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 spec

Anti-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 → Verify

Core Concepts

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. 1

    Feature idea

    A need emerges

  2. 2

    shape-spec

    Structured conversation — clarify, don't assume

  3. 3

    requirements.md

    Living doc — stories, criteria, open items

  4. 4

    Clarification Gate

    Open items = 0?

  5. 5

    Generate & implement

    Tasks, plans, prompts, code

Gate condition: open items = 0 → then generate tasks & implement

Key Terms

TermDefinition
SDLCSoftware Development Life Cycle — phased process from requirements to maintenance
PRDProduct Requirements Document — structured description of what to build and why
TDDTest-Driven Development — write failing tests first, then code to pass them
BDDBehavior-Driven Development — given/when/then scenarios as executable specs
SDDSpec-Driven Development — version-controlled, executable specs for AI and humans
Vibe-codingPrompting AI without structured specs; outcomes depend on luck
AI EngineeringDirecting AI with clear, executable specifications for predictable results
shape-specStructured conversation process to clarify feature requirements
Clarification GateBlocker requiring zero open items before implementation
Executable intentSpecs detailed enough to auto-generate tasks, plans, and prompts
Living documentA spec that evolves with the project, tracked in version control
Development stagesSpecification → Plan → Tasks → Code → Verify — the ordered pipeline from intent to verified software

Practical Takeaways

  1. 1Spec over code. Ask what the spec says should happen — not what the code happens to do.
  2. 2SDD stands on shoulders. SDLC, PRDs, TDD, and BDD each solved part of the problem — SDD composes them for the AI era.
  3. 3Never skip shaping. A 15-minute spec conversation saves hours of rework.
  4. 4Specs live in the repo. If it is not in git, it does not exist.
  5. 5Open items are stop signs. Resolve them before coding.
  6. 6Write for execution. If AI cannot generate a task from your spec, rewrite it.
  7. 7Stories describe goals. Let implementation emerge from clear intent.
  8. 8Follow the stages. Specification → Plan → Tasks → Code → Verify — never skip ahead.

Next: shape-spec workflow

Structured feature shaping checklist and phases.

Open shape-spec →