Why Vibe Coding Fails and How Specification‑Driven Development Can Save AI‑Assisted Coding

Vibe Coding’s Five Fatal Flaws

In early 2025, Andrej Karpathy coined “Vibe Coding”, a trend where developers describe intent in natural language and let AI generate code. While it can boost short‑term efficiency, the article identifies five critical issues:

Requirement evaporation – important decisions disappear in chat and are not persisted.

Context drift – limited window size causes overflow of information.

Unreviewable – design intent is scattered across dialogs without structured artifacts.

Irreproducible – past implementations cannot be traced, making fault fixing harder.

Unmaintainable – the combination of the above makes projects hard to understand, fix, and evolve.

Why a New Paradigm Is Needed

The author argues that developers must adopt a new software development paradigm to avoid these pitfalls.

Specification‑Driven Development (SDD)

SDD is presented as an AI‑native methodology where the human engineer’s primary output is a structured specification document, and code is a derivative produced by AI. The specification serves as the single source of truth, is version‑controlled, reviewable, and traceable.

Core principles:

Specification first.

Specification is documentation.

Specification is executable.

Specification is under version control.

Code serves the specification.

Three‑Phase Learning Path

Phase 1 – Recognize the Problem : Analyzes a real “three‑day collapse” project case, compares waterfall, agile, and SDD, and outlines the historical evolution from contract‑based design (1988) to API‑First (2015) to AI‑native SDD (2025).

Phase 2 – Master the Method : Details the end‑to‑end workflow, including the six‑stage process and three core documents – proposal.md (requirements), design.md (architecture), and tasks.md (task execution). Describes tool ecosystems (OpenSpec, Spec‑Kit, BMAD) and integration with Claude Code, Cursor, GitHub Copilot, Kiro. Provides a comparison of specification formats (Markdown, YAML, JSON Schema) and guidance on repository layout, pre‑review, and feature branches.

Practical demonstrations include:

Transforming fragmented verbal requirements into a structured proposal.md with a template and quality checklist, assisted by Claude Code.

Writing module contracts, data models, and non‑functional constraints in design.md, introducing ADR (Architecture Decision Records).

Decomposing tasks.md using a “one task, one verifiable deliverable” rule, managing dependencies with a DAG, and defining acceptance criteria for single‑agent and parallel sub‑agent workflows.

Building a layered test system that synchronizes specification updates with code changes, and a gradual approach for legacy projects.

Phase 3 – Deep Application : Explores integration of SDD with five Agent design patterns (planning‑execution, generation‑review, hierarchical delegation, guard‑sandwich, conditional routing). Shows how SDD specifications can be stored in CLAUDE.md, validated via hooks, and used to dispatch tasks to sub‑agents. Discusses team roles (spec writer, reviewer, executor), PR review process, and alignment with Scrum and CI/CD pipelines, including measurable impact metrics.

The section also predicts the long‑term evolution from AI‑assisted coding to autonomous agents and posits “specification is code” as the ultimate industry vision.

Book Overview

The accompanying book, “SDD in Practice: The Path to Specification‑Driven Development,” uses the above analysis as a foundation, providing a complete six‑stage project example (“Intelligent Daily Report Generator”) and a reusable template for AI‑assisted development.

Author Huang Jia (pen name “Ka‑Ge”) is a senior AI researcher with experience in large models, agent systems, and engineering. His previous works include “Claude Code in Practice” and “Agent Design Patterns.”