Spec-Driven Development: Why Vibe Coding Is a Debt Trap for Agent Teams

Vibe coding makes one developer faster and the team slower. Spec-driven development makes the specification the contract that governs coding agents. What that looks like in a repository, and where it still falls short.

TL;DR

  • Vibe coding speeds up the individual and slows down the team, and three studies now put numbers on the slowdown.
  • Spec-driven development (SDD) makes the specification the contract between humans and agents: the spec is what you maintain, code is what the agent derives from it.
  • The contract has two halves: limits enforced around the agent at runtime, and review and governance enforced around the team.
  • Use it for code that will outlive a sprint. Skip it for throwaway work.

Vibe coding is fast for one developer and slow for the team

Vibe coding: describe what you want, let the agent write it, glance at it, move on. For one developer on one afternoon it works. The trouble starts when a team does it.

Researchers studying agentic software engineering name it a productivity paradox: as individual productivity rises, team throughput, review capacity and stability fall, because the team-level engineering discipline gets dropped. In METR's randomized trial, 16 experienced open-source developers working in repositories they knew well were 19% slower with AI, while believing it had sped them up. CodeRabbit's analysis of 470 open-source pull requests found logic and correctness errors 75% more common in AI-authored ones. GitClear's analysis of 211 million changed lines found short-term churn, code rewritten or reverted within two weeks, more than doubled from 3.1% to 7.1%.

None of these is conclusive alone. The trial is small, and churn is a correlation, not a cause. Together, though, they describe a cost that one practitioner calls the Verification Tax: agent code needs more careful review than a colleague's, because it fails differently. It is confident and subtly wrong, it misses edge cases, and it introduces security anti-patterns without warning. That review work is debt, and vibe coding defers it until someone else pays.

Specifications as the contract substrate between humans and agents

Spec-driven development changes what the team treats as durable. Diaz and colleagues describe specifications as the contract substrate between humans and agents, and they argue SDD rebuilds what vibe coding dissolves: accountability, verifiability and transferability. In a vibe-coded repository the prompt behind a module is gone. In an SDD repository its spec is versioned next to it.

They split enforcement into two harnesses. For an architect, the split is the useful part.

The technical harness sits around the agent and is where formal contracts live. Agent Behavioral Contracts bring Design-by-Contract to agents: each contract names preconditions, invariants, governance policies and recovery mechanisms, all enforced at runtime. Agent Contracts do the same for resources. They exist because a multi-agent system with no stop conditions, no budget limits and no real-time cost monitoring can loop unnoticed until the invoice arrives. An Agent Contract moves through explicit states (DRAFTED, ACTIVE, then FULFILLED, VIOLATED, EXPIRED or TERMINATED), and when one agent delegates to another, a conservation law keeps the child's budget inside the parent's.

The methodological harness sits around the team: who writes the spec, who reviews it, and what the repository refuses. Neither harness is enough alone. Runtime limits without review give you cheap wrong code. Review without limits gives you a loop that runs until somebody reads the bill.

What an SDD workflow looks like in a repository

An undergraduate project course ran SDD in four phases: investigation, planning, implementation and review. That is a sensible default shape. This is how I would fill each phase with tools that already exist.

  1. Investigation. Write a project constitution with the agent: mission, tech stack, roadmap. Every later spec inherits it.
  2. Planning. Write a Markdown spec per feature: behaviour, constraints, acceptance tests. Commit it before any code.
  3. Implementation. Give the agent the spec and repository-local guidance, as the AI-SDLC approach does with specifications, an agent instructions file and phase-specific skill files. The agent gets room to work inside a lifecycle the team can still review and test.
  4. Review. Gate commits on scope. Squelette, for example, has each work item declare the file paths it may touch, and its pre-commit gate refuses anything outside them. Human decisions get recorded in the repository.

When a requirement changes, change the spec and re-run the loop. Be clear with your team about what that means: you run an agent you still supervise over the updated spec, then you review the result. The spec is not a compile button, and the output will differ from one run to the next.

When to adopt SDD, and where it still falls short

Adopt it for code that will outlive a sprint, cross a service boundary, or face an audit. The spec tells future maintainers why the code is the way it is.

Skip it for throwaway scripts, one-off notebooks and spikes, where the spec costs more than the code is worth.

Budget-bound contracts pay back in cost, too. The Agent Contracts authors report a 90% token reduction in iterative workflows across four experiments. Parallel agent patterns pull the other way: Google's architecture guidance notes that running agents in parallel cuts latency but raises token consumption and operating cost. Reach for them when latency is the requirement, and leave them off otherwise.

The limits are real. The course study found agents raised implementation throughput but let students move on without understanding the code. A spec does not transfer understanding by itself. At AIware 2026, Amazon's Rajdeep Mukherjee named the open challenges: spec completeness, ambiguity, trust and semantic alignment. A vague spec produces confident, wrong code as reliably as a vague prompt does.

What to do this week: pick one service with a compliance or longevity requirement. Write its constitution and one feature spec. Put a scope gate on commits and a budget on every agent run. Then review the specs as carefully as the diffs.

Sources

aispecificationsoftware‑architectureagentic‑codingtechnical‑debt

All writing