Spec-Driven Dev: Markdown Specs Before AI Code Gen

The Breakthrough

Spec-Driven Development requires developers to write a structured markdown specification describing features, constraints, and edge cases before AI coding agents generate any code; the spec serves as the single source of truth that agents match and developers verify.

What Actually Worked

• Developers start with a high-level spec; the AI asks clarifying questions such as data storage location, timeout handling, and user-facing errors; developers answer to eliminate ambiguity.
• The AI generates a technical plan and breaks it into small tasks; developers approve the plan before implementation.
• The AI implements each task incrementally; developers review diffs against the spec; tests generate from acceptance criteria in the spec.
• GitHub Spec Kit provides an open-source toolkit (92K stars) that works with any AI agent via github init command; Amazon Kiro integrates specs into a cloud-based IDE; Tessl forbids direct code edits and requires spec updates to regenerate code.
• SDD suits greenfield projects, cross-surface migrations, compliance-heavy work, complex features with high ambiguity, and long AI sessions where agents might lose context.

Before / After

• METR study (July 2025) found experienced developers using AI tools were 19% slower overall while perceiving a 20% speedup.
• Faros AI telemetry from 10,000 developers showed +21% individual task completion, +91% pull request review time, and +9% bugs per developer.
• Colin Eberhardt's head-to-head test: Spec Kit took 33 minutes of agent time, produced 2500 lines of markdown for 689 lines of code, and required 3.5 hours of review; iterative coding took 8 minutes of agent time, produced 1000 lines of code, and required 24 minutes of review with no bugs.

Context

Vibe coding—prompting AI, accepting output without review—speeds prototypes but generates wrong code faster, inflating PR reviews and bugs as shown in METR and Faros data. Spec-Driven Development provides AI agents with literal blueprints, collapsing iteration costs from months (waterfall) to minutes. It addresses AI's literal-minded hallucinations but faces spec drift (specs become outdated post-ship) and determinism issues (same spec yields varying code from probabilistic models). Developers benefit by honing precision in describing code intent for machine execution.

Notable Quotes

• "That's not waterfall. That's agile wearing a trench coat." — Roger Wong
• "Vibe coding: you prompt an AI accept whatever it spits out never read the diffs and pray." — Andrej Karpathy

Content References

References appear in video description and transcript citations.