What are the main problems with spec-driven development?

Volume of generated markdown, reviewing both the spec and the code, agents that ignore or over-interpret the spec, rigid workflows for small changes, and difficulty on large existing codebases. Underneath all of them is spec drift: specs that guided the first build and were never updated.

The gap that grows between what a spec says and what the software does, through small changes that never get written back. In spec-driven development it is worse, because the next AI agent reads the old spec as current instructions.

Should specs be updated after the feature ships?

The rules should. Spec Kit leaves the choice to each team: treat feature directories as an immutable record, maintain them as a living contract, or reconcile discoveries back after the fact. A practical split is to keep requirements and constraints living and let plans and task lists stand as history.

When should a team skip spec-driven development?

For small changes, prototypes, and exploratory work where the requirements are still being discovered. Writing a full spec for a date field costs more than it saves. Use it where a misread requirement is expensive.

Spec-driven development problems: the real one is drift

Q: Is spec-driven development just waterfall?

Not by design. Waterfall specifies a whole system up front; spec-driven tools work one feature at a time, and Spec Kit's guidance for existing projects is to start with a bounded change that can be reviewed on its own. But a long spec for a small change can feel like waterfall, and critics like François Zaninotto argue it often is.

François Zaninotto tried spec-driven development on a small change: adding a date field. The tool produced 8 files and 1,300 lines of text. His post, titled "Spec-Driven Development: The Waterfall Strikes Back", reached 225 points on Hacker News.

He is not alone. Birgitta Böckeler's review of Kiro, Spec Kit, and Tessl on martinfowler.com found the generated markdown repetitive and tedious to review. Searches like "is spec driven development just waterfall" and "why spec driven development does not work" now appear in Google's suggestions.

The complaints are mostly fair. But they describe the cost of writing specs. The bigger cost arrives after the first build, and it gets less attention.

The common complaints, and which are fair

Most criticism of spec-driven development falls into five groups:

Complaint	Who raised it	Fair?
Too much generated markdown	Zaninotto: 1,300 lines for a date field. Böckeler: repetitive, tedious to review	Yes, for small changes
Double review: the spec, then the code	Zaninotto	Yes. A spec doesn't remove code review
Agents still ignore or over-interpret the spec	Böckeler	Yes. A spec improves the odds, not the guarantee
One rigid workflow for every size of problem	Böckeler	Partly. Teams can skip it for small work
Unusable on large existing codebases	Zaninotto	Partly. Tools now ship guidance for existing projects

Each of these is about effort: time spent writing and reviewing documents. They are real, and a team can manage them by using specs only where a misread requirement is expensive.

Is spec-driven development just waterfall?

Not by design, but it can feel like it. Waterfall specified a whole system before building any of it. Spec-driven tools work one feature at a time. Spec Kit's guidance for existing projects says to start with a feature or modernization slice that can be reviewed independently, rather than documenting the whole system first.

The waterfall feeling comes from proportion. When the spec is ten times longer than the change, the team is doing big design up front at a small scale. That is a sizing problem, and it is solvable: shorter specs, and no spec at all for trivial changes.

The harder problem is not up front. It is afterwards.

The problem underneath: specs stop being true

Böckeler describes three levels of spec-driven development. In spec-first, the spec guides the first build and is then discarded. In spec-anchored, the spec is kept and evolves with the code. In spec-as-source, people edit only the spec and never the generated code.

Most teams land on spec-first without choosing it. Spec Kit's own documentation is candid that this is a choice left to the team. After the first change, it lists three ways to maintain feature artifacts:

Treat each feature directory as an immutable historical record.
Maintain specs as a living contract and regenerate downstream artifacts.
Let discoveries flow back from code, tasks, or plans, then reconcile the full artifact set.

The first option takes no effort, so it is what happens by default. The spec becomes a snapshot of what the team intended on one day.

Why drift is worse when agents read the spec

Here is how a spec goes stale in practice. The invitations spec says links expire after 7 days. Three weeks after launch:

A customer call changes it to 14 days. The engineer edits a constant. Nobody edits the spec.
A pull request adds an exception for enterprise accounts. It is discussed in review, not in the spec.
A Slack thread decides to block personal email domains. The spec still lists it as an open question.

With human readers, a stale spec is mostly harmless. People know it is old and ask someone. An AI coding agent doesn't know. When the next feature touches invitations, the agent may read the old spec directory as context and treat "7 days" and "personal domains allowed" as current rules. It then writes confident, consistent code against a product that no longer exists, and the change passes review because the code matches the spec.

That is spec drift. Spec-driven development makes specs more influential, which makes stale specs more expensive.

Keep the rules living, let the rest expire

Not every part of a spec needs to stay true. A practical split:

Part of the spec	After the build	Why
Requirements, rules, constraints	Keep living	Future work must follow them
Non-goals and open questions	Keep living, resolve over time	An open question that got answered is now a rule
Technical plan	Let it stand as history	The code is now the source of truth for how
Task list	Let it stand as history	Done is done

That turns an impossible job, keeping 1,300 lines in sync, into a small one: keeping a short list of numbered rules current. Then treat each rule as a decision:

Give each rule an owner. The PM for product rules, the tech lead for technical constraints.
Change rules by adding a new version. "R1: 7 days, replaced on 12 November by R1 v2: 14 days, approved by the PM." The old one stays visible.
Write back decisions made elsewhere. A rule changed in a PR comment or a Slack thread is still a spec change.
Brief the next agent from the current rules, not from whichever spec directory it happens to find.

For the product side of writing the rules in the first place, see spec-driven development for product managers.

When to skip spec-driven development

Zaninotto's alternative, short iterative instructions and small experiments, is the right call for a lot of work. Skip the full spec workflow for:

Small changes where the code is shorter than any spec would be.
Prototypes and spikes where you are still discovering what to build.
Bug fixes with an obvious cause.

Use it where a misread requirement is expensive: pricing, permissions, data handling, anything another team depends on. Even then, the part worth keeping is the rules, not the volume.

Where Lockstep fits

Lockstep keeps the living part of a spec current after the first build. Requirements and decisions are captured from PRDs, Slack, and pull requests, and each becomes binding when its owner approves it. When one changes, the new version replaces the old one and the old one stays visible as replaced. Claude Code is briefed on the current rules that apply at the start of each session, and an opt-in check can flag code changes that may conflict with one.

It does not generate specs, plans, or tasks, and it does not replace Spec Kit or Kiro. It does not guarantee an agent follows a rule; the check is advisory. Session briefings work with Claude Code today. See how it works.

Sources checked 4 November 2026

For writing the spec as a product manager, see spec-driven development for product managers. For checking a build against requirements, see how do I know engineering built what the PRD said?. For the term, see spec drift.

Frequently asked questions