Spec-Driven Development

From waterfall to vibe coding and back to specs

Photo: Kiban — CC BY-SA 3.0 / Wikimedia Commons

BETA

Prehistory

SDLC before AI

Idea → Release, the old way

flowchart LR
  I@{ icon: "lucide:lightbulb", form: "circle", label: "Idea", pos: "b", h: 50 }
  R@{ icon: "lucide:clipboard-list", form: "square", label: "Requirements", pos: "b", h: 40 }
  D@{ icon: "lucide:palette", form: "square", label: "Design & Prototype", pos: "b", h: 40 }
  Impl@{ icon: "lucide:code", form: "square", label: "Implementation", pos: "b", h: 40 }
  AT@{ icon: "lucide:flask-conical", form: "square", label: "Automated Tests", pos: "b", h: 40 }
  U@{ icon: "lucide:clipboard-check", form: "square", label: "UAT", pos: "b", h: 40 }
  Dep@{ icon: "lucide:server", form: "square", label: "Deployment", pos: "b", h: 40 }
  Rel@{ icon: "lucide:rocket", form: "circle", label: "Release", pos: "b", h: 50 }
  I --> R --> D --> Impl --> AT --> U --> Dep --> Rel
  class R,U pm
  class D designer
  class Impl,AT,Dep engineer
  classDef pm fill:#eef0ff,color:#111928,stroke:#788cfc
  classDef designer fill:#fdf2f8,color:#111928,stroke:#c084fc
  classDef engineer fill:#def7ec,color:#111928,stroke:#25b51f
  • Idea → Requirements — "I know it when I see it" turns into a 40-page PRD nobody reads
  • Requirements → Design — designer interprets without full context; assumptions bake into mockups
  • Design → Implementation — engineer opens Figma and asks "…what happens when there's no data?"
  • Implementation → Automated Tests — CI/CD catches regressions and code bugs on every commit — the feedback loop engineers earned
  • Automated Tests → UAT — happy path clicks through; edge cases slip past a walkthrough
  • UAT → Deployment — each fix invites another; deadlines slip quietly
  • Deployment → Release — green pipeline, red stakeholders: "that's not what I meant"
  • Overall — no single contract survives the handoffs; specs age faster than they ship

The Era of Vibe Coding

Prompt → generate → ship

What It Is

flowchart LR
  I@{ icon: "lucide:lightbulb", form: "circle", label: "Idea", pos: "b", h: 50 }
  P@{ icon: "lucide:message-square", form: "square", label: "Prompt", pos: "b", h: 40 }
  G@{ icon: "lucide:sparkles", form: "square", label: "Generate", pos: "b", h: 40 }
  S@{ icon: "lucide:rocket", form: "circle", label: "Ship", pos: "b", h: 50 }
  I --> P --> G --> S
  class P human
  class G ai
  classDef human fill:#e0e7ff,color:#111928,stroke:#6366f1
  classDef ai fill:#fef3c7,color:#111928,stroke:#f59e0b

Vibe coding = prompt → generate → ship, done by one person in real-time. No handoffs, no formal spec, no review gate.

Pros

  • Lightning-fast velocity — working code in minutes, not sprints
  • Low barrier to entry — you don't need to know a language to try an idea
  • Democratised — PMs, designers, non-devs can prototype directly
  • Great for prototypes and solo projects — throwaway code is fine
  • Cheap experimentation — try three approaches in an hour

Cons

  • Single contributor at a time — context lives in one chat window
  • Manual QA — no automated tests; every change re-verified by hand
  • Security concerns — AI can hallucinate insecure patterns
  • Non-deterministic — same prompt, different day, different output
  • Hidden complexity — code that "works" but nobody understands
  • Vendor lock-in — code, prompts, and workflow live inside one SaaS

The Tradeoff

Brilliant for solo prototypes and one-person exploration.

Hostile to teams, longevity, and anything that needs to be trusted.

Spec-Driven Development

Write the plan before the code

What It Is

Write a detailed, reviewable implementation plan before writing code.

Why

  • Traditional SDLC fails on speed — Waterfall specs are slow to write and rigid; by the time code ships, requirements have moved
  • Vibe coding fails on alignment — No spec means no contract
  • Traceability is non-negotiable — Every line of code must trace back to a documented decision
  • AI needs a spec — Without structure, agents hallucinate architecture, duplicate logic, and produce unreviewable output
  • Risk reduction — Catching a wrong architecture decision in a spec costs minutes; catching it in production costs days

How

  1. Investigate — PM explores current system: data model, existing patterns, feature maps, open tickets
  2. Spec — Write a structured implementation plan: context, architecture, data model, file tree, sequencing, rollback, testing
  3. Validate — Lightweight prototype or visual mock so stakeholders confirm direction
  4. Develop — Implement against the frozen spec; AI agents execute predictably
  5. Review — Architecture review validates compliance against the spec, freeing code review for logic
  6. Ship — Update Linear tickets, CI/CD, release notes

Demo: SD-366

Open SD-366_Implementation_Plan.md on GitHub:

  • Overview and context
  • Architecture decisions (multi-3PL, mirror vs live fetch)
  • Phased breakdown (schema → sync → endpoint → FE)
  • Code structure with exact file trees
  • Sequencing and dependencies
  • Testing, rollback, observability

Pros

  • Alignment — everyone agrees on what before how
  • Reviewable — architects and PMs review the plan, not just the code
  • Traceable — every ticket links to a decision in the spec
  • AI-scalable — AI agents execute against a well-structured spec

Cons

  • Upfront investment — writing a good spec takes time
  • Requires discipline — skipping the spec defeats the purpose

When to Use It

  • Complex features
  • Architectural changes
  • Multi-team efforts

Skip it for trivial bug fixes.

Thanks.

Spec it. Build it. Ship it.