Spec-driven development with AI works surprisingly well in isolation. You write a concise spec, let an agent generate the implementation, and get clean results on the first run. No endless prompt tweaking required.
The illusion breaks the moment you bring this into a team. The question shifts immediately from “does this work?” to: “How does this hold up with five engineers on a shared repository over the next six months?”
Most guides stop at “here is what a good spec looks like,” treating SDD purely as an individual prompting technique. But a working prototype tells you almost nothing about team scale. The real friction doesn’t appear in the first session; it builds up quietly when requirements evolve, architectures shift, and several people work against the same shared contract over time. This is the first of three parts: this one sets up the diagnosis, the next covers the mechanism, and the third is the rollout playbook.
A maturity model, not a checklist
Spec-driven development often gets treated as if there were only one correct way to do it. That’s not quite right. A model originally put forward by Birgitta Böckeler at Thoughtworks, and picked up widely since, splits SDD into three maturity levels. These aren’t steps you’re required to climb in order. They’re three different destinations with different price tags.
Spec-First is where most teams that believe they’re doing SDD actually sit. The spec gets written before the code, and then nobody touches it again. It quietly turns into a relic. There’s a familiar version of this from an older corner of IT history: the Word doc on the shared drive that was written at kickoff and hasn’t been opened in two years, because the code moved on without it.
Spec-Anchored is the state where the spec stays with a feature for its entire lifecycle, kept up to date as things change rather than frozen at the first draft. This is the level that pays off when several people or teams share a contract: the spec is something everyone can actually rely on, not a snapshot from three months ago.
Spec-as-Source goes further still. The spec becomes the only artifact a human edits directly; code is generated and never touched by hand. Interesting, but for now this fits narrow, deterministically checkable domains far better than the ordinary business logic of a system that’s already grown messy over the years.
Here’s the catch: Spec-Anchored sounds like the obvious target, right up until you notice it comes with a structural trap.
The risk nobody accounts for: spec rot
Moving from Spec-First to Spec-Anchored has a cost: process overhead, review discipline, and continuous upkeep. The payoff is a spec that stays current. The failure mode is paying that overhead without getting the payoff, because the spec goes stale anyway.
That is spec rot: carrying the ongoing cost of Spec-Anchored while slipping right back into the reality of Spec-First.
A simple example makes the difference concrete. If you build a feature alone, write a spec, tweak the implementation two weeks later, and forget to update the document, you will probably remember the delta. On a team, context doesn’t travel that easily. A colleague reads that same spec six months later while building an adjacent feature. She trusts it because it sits in the repo with an owner attached. Except it no longer describes the actual code.
And an AI coding assistant won’t catch the divergence either. In fact, LLMs make spec rot significantly more dangerous: they will generate syntactically clean, highly confident code based entirely on an outdated premise.
That is the fundamental difference between solo and team workflows: the spec quality doesn’t degrade any faster, but who notices the gap changes completely. Solo, you spot it. In a team, nobody does, until an integration breaks.
A simple diagnostic cuts straight to the core: does anyone actually read and update these spec files? If the honest answer is “not really,” the team is running Spec-First, regardless of what tooling is installed.
Why this stays invisible on one team and turns real on several
On a single team with a single repository, spec rot can stay hidden for months. Shared mental context compensates for documentation gaps, and the blast radius remains local.
Once multiple teams build against shared interfaces, implicit assumptions collapse. Two teams rely on the same spec from different vantage points. If Team A alters implementation details without propagating the spec changes, a quiet divergence opens up: both sides believe they agree on the contract, but they are working against two different versions of reality. This is the exact root cause behind expensive multi-team integration failures.
Which leads to the foundational question: where does the authoritative contract actually live, and what is merely a view onto it?
One source of truth
A principle that holds up in practice fits in a single sentence:
There can only be one authoritative version of a specification. Everything else is a projection of it, not a second copy.
Compare the two most common candidates for owning specifications:
| Criterion | Repo (Git) | Jira as a spec store |
|---|---|---|
| Versioning / diffing | Native, complete history | Free-text history only, no line-diffing |
| Link to the code | Commit ties spec and code atomically | Reconstructed manually via ticket IDs |
| Review mechanics | Pull request review, line by line | No formal review tooling for text fields |
| Automated checks | CI validates structure and schema | Hard to automate reliably |
| Access for non-technical stakeholders | Poor | Excellent |
Git wins decisively on technical governance. Jira’s one real advantage, stakeholder accessibility, is often the one that decides these debates in practice.
A workable split avoids both extremes: forcing product managers into raw Git, or letting Jira turn into an ungoverned wiki. The repository stays the single authoritative source of truth. Jira and Confluence work as strict read-only projections, Git → Jira, an accessible shop window with no authority to fork the contract.
What follows from this
Wanting Spec-Anchored is not enough. Without a reliable way to make spec maintenance measurable rather than a matter of goodwill, teams inevitably drift back into Spec-First, paying the governance tax without getting the reliability.
Part 2 of this series tackles that mechanism: how to turn the subjective question “can we still trust this spec?” into an automated, observable signal derived directly from repository activity, without bogging down daily PRs in bureaucracy.
Part 2: Making spec rot visible before it breaks the build.