Follow along

spec-driven-development.pages.dev

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

Spec-Driven Development

Write a detailed, reviewable implementation plan before writing code.

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 }
  Gen@{ icon: "lucide:sparkles", form: "square", label: "Generate", pos: "b", h: 40 }
  Proto@{ icon: "lucide:mouse-pointer-click", form: "square", label: "Interactive Prototype", pos: "b", h: 40 }
  V@{ icon: "lucide:check-circle", form: "square", label: "Validate", pos: "b", h: 40 }
  I --> R --> Gen --> Proto --> V
  V -->|Refine| R
  class R,Proto pm
  class V stakeholder
  class Gen ai
  classDef pm fill:#eef0ff,color:#111928,stroke:#788cfc
  classDef ai fill:#fef3c7,color:#111928,stroke:#f59e0b
  classDef stakeholder fill:#ccfbf1,color:#111928,stroke:#14b8a6
Ready ↓
flowchart LR
  Spec@{ icon: "lucide:file-text", form: "square", label: "Spec", pos: "b", h: 40 }
  Plan@{ icon: "lucide:list-checks", form: "square", label: "Plan Tickets", pos: "b", h: 40 }
  Impl@{ icon: "lucide:code", form: "square", label: "Implement", 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 }
  Ship@{ icon: "lucide:rocket", form: "circle", label: "Ship", pos: "b", h: 50 }
  Spec --> Plan --> Impl --> AT --> U --> Ship
  class Spec,U pm
  class Plan ai
  class Impl,AT,Ship engineer
  classDef pm fill:#eef0ff,color:#111928,stroke:#788cfc
  classDef engineer fill:#def7ec,color:#111928,stroke:#25b51f
  classDef ai fill:#fef3c7,color:#111928,stroke:#f59e0b

The spec is the source of truth

  • PMs write it — one document, iterated with stakeholders, before engineering starts
  • Stakeholders read it — and sign off before code exists
  • Engineers read it — every ticket links back to a documented decision
  • AI agents read it — structure eliminates hallucination and drift

How — product_trego

PM investigation workspace for TREGO.

frontend/ and backend/ live as read-only git submodules

Claude skills drive the SDD loop.

product_trego/
├── CLAUDE.md                       # rules: audience = PM, submodules read-only
├── frontend/                       # git submodule → pandago-saas (read-only)
├── backend/                        # git submodule → smart-delivery-backend
├── prototypes/                     # named worktrees off origin/dev
│   ├── 8081-dashboard-redesign/
│   ├── 8082-live-ops-dashboard/
│   └── …
├── prototypes.json                 # registry of live sandboxes
└── .claude/skills/
    ├── prd/                        # PRD from real code + Notion strategy
    ├── prototype-create/           # spin up isolated sandbox off origin/dev
    ├── prototype-start / -stop / -list/
    ├── frontend-feature-map/       # investigation: screens, roles
    ├── frontend-user-flow/         # investigation: step-by-step flows
    ├── backend-data-model/         # investigation: entities, lifecycles
    ├── backend-tech-stack/         # investigation: deps, env, third parties
    ├── sync-submodules/            # pull latest, PM-language summary
    ├── git-buddy/                  # narrates every git command
    └── setup-mcp-linear-notion/    # connect ticketing + docs (OAuth)

Demo

Pros & Cons

Pros

  • Alignment — everyone agrees on what before how
  • Reviewable — developers 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
  • Eliminate bad ideas early — kill flawed proposals before implementation
  • Better quality — a well-crafted spec produces higher-quality output

Cons

  • Upfront investment — writing a good spec takes time
  • Requires discipline — skipping the spec defeats the purpose
  • Minimum technical knowledge — diy vide coding require some basic tech skill
  • Not as fast as vibe coding — upfront planning trades speed for structure

Thanks.

Spec it. Build it. Ship it.