Hichoi-Dev

Posted on Mar 18

Why Spec-Driven Development Fails— And a Better Way to Structure AI Development

#ai #productivity #softwaredevelopment #softwareengineering

SDD: The Right Problem, Wrong Solution

Spec-Driven Development (SDD) is the idea that detailed specifications — written upfront — can guide AI agents to produce working software. GitHub's Spec Kit is a representative example, formalizing this into a workflow: Specify → Plan → Task → Implement.

SDD recognized a real problem: "prompt and pray" doesn't scale. Beyond toy projects, you need a way to communicate intent to AI that goes beyond "build me an auth system." The core insight — that structure matters — is valid.

The Core Problem: Specs Are Non-Deterministic

The fundamental flaw: SDD treats specifications as authoritative sources of truth, but LLMs exhibit non-deterministic behavior. The same specification produces different implementations across different runs—varying architectural choices, data structures, and error handling. As the analysis notes, "Because of the non-deterministic nature of this technology, there will always remain a very non-negligible probability that it does things that we don't want." This means specifications cannot serve as reliable sources of truth the way source code does.

SDD Is Waterfall in Disguise

SDD essentially recreates Waterfall methodology:

Big Design Up Front with exhaustive specifications
Sequential phases completing before the next begins
Assumption that thorough planning eliminates execution uncertainty

Real-world testing revealed inefficiency: one hands-on evaluation required 33 minutes and 2,577 lines of markdown to produce 689 lines of code, compared to 8 minutes using iterative prompting—approximately 10x slower with no quality improvement.

Why Specifications Drift

Specifications and code inevitably diverge because:

AI makes unanticipated architectural choices
Each iteration accumulates undocumented decisions
Specs become post-hoc documentation rather than guides
Developers spend time reading lengthy markdown instead of solving problems

The Real Question

Rather than "exhaustive upfront specifications," the answer aligns with decades of software engineering wisdom: iterative development with accumulated learning—essentially Agile methodology adapted for AI collaboration.

A Different Approach

This is what motivated me to build REAP (Recursive Evolutionary Autonomous Pipeline). Rather than treating development as a spec-to-code translation, REAP structures AI-assisted development as an evolutionary process — closer to how experienced developers actually work.

How REAP Works

Development happens in Generations. Each generation carries one focused goal through a 5-stage lifecycle:

Objective → Planning → Implementation → Validation → Completion

This isn't just a linear pipeline. Each stage has gates, and stages can regress — if validation fails, you loop back to implementation with the failure context preserved. This mirrors the real-world "build → test → fix → test again" cycle that SDD's sequential model ignores.

The Genome: Knowledge That Evolves

Where SDD puts specifications at the center, REAP puts a Genome at the center — a living record stored in .reap/genome/:

principles.md — Architecture decisions with rationale (ADR-style)
conventions.md — Development rules and enforced standards
constraints.md — Technical choices and validation commands
domain/ — Business rules that can't be derived from code

The Genome isn't written once and forgotten. It evolves across generations. When you discover something during implementation that contradicts the Genome, you log it as a backlog item. At the end of each generation, discoveries are reviewed and the Genome is updated. Over time, the Genome becomes an increasingly accurate map of your project — not a spec that drifts from reality.

What Makes It Different from SDD

	SDD	REAP
Source of truth	Specification document	Evolved Genome + source code
Planning scope	Entire project upfront	One generation at a time
When plans break	Spec drift → update spec → regenerate	Discovery → backlog → evolve Genome
Validation	Spec compliance	Actual tests, type checks, builds
Knowledge persistence	Specs (static)	Genome (evolving) + Lineage (history)
Context for AI	Spec document	Genome + generation state (auto-injected)

Context That Persists

Every time you start an AI session in a REAP project, the SessionStart hook automatically injects the Genome, current generation state, and workflow rules into the AI's context. The AI doesn't start from zero — it starts with your project's accumulated knowledge.

This solves SDD's "spec drift" problem at the root. The Genome stays in sync with reality because it's updated as part of the development process, not maintained as a separate artifact.

Try It

npm install -g "@c-d-cc/reap"
reap init my-project
# Open Claude Code or OpenCode
> /reap.start
> /reap.evolve "Implement user authentication"

REAP supports multiple AI agents — Claude Code and OpenCode today, with an extensible adapter system for adding more.

GitHub | Documentation | npm

What's your experience with spec-driven development? Have you found structure that works for AI-assisted development? I'd love to hear in the comments.

References:

DEV Community