We went through 20,000 comments about specs. Here is what breaks.

Published 18 October 2026

In fifteen months, spec-driven development went from almost nothing to 2,500 new GitHub repositories a quarter. We read what the people using it say goes wrong — and what the agencies whose clients have to approve the specs say goes wrong. It is the same failure on both sides: the specification lives in more than one place, nothing downstream is told when it changes, and the people who have to agree with it cannot read it.

What we looked at

20,201 comments, issues and posts in all. We kept 501 quotes — 299 from developers, 202 from agencies, analysts and product managers — and every quote on this page was checked word for word against its source on 18 October 2026.

From nothing to everywhere

Hacker News comments mentioning “spec-driven”:

New GitHub repositories with “spec-driven” in their name, description or topics:

On 17 October 2026, GitHub’s Spec Kit had 141,651 stars, OpenSpec 72,234 and BMAD-METHOD 54,262 (how the three compare). Over the same years, Hacker News comments using the words “stale documentation” stayed between zero and five a year. People do not name the old problem any more. They name a new one: “spec drift” appeared in no comment before 2025, in 2 in 2025, and in 14 so far in 2026 (what spec drift is, and how to stop it).

What breaks for the people writing the specs

Ranked by how often it came up in the 299 developer quotes, and how much attention the threads drew.

1. The agent’s own notes go stale

We set up a CLAUDE.md early on and it was great for about a month. Then we refactored a couple of modules, changed our deploy flow, and nobody updated the file. Claude kept confidently working off rules that stopped being true weeks ago.

— a five-person team, r/ClaudeAI, July 2026

2. Too much to review

every change, medium or larger, turns into a large set of multiple markdown documents, each that need review.

— a developer whose company adopted OpenSpec, Hacker News, September 2026

To be honest, I’d rather review code than all these markdown files.

— Birgitta Böckeler, martinfowler.com, October 2025

3. The spec drifts from the code after the first build

In my experience, spec drift is the main reason why none of these tools work.

— Hacker News, September 2026

The people behind the tools say so too. On the day Kiro launched, the author of a guide in Kiro’s own documentation wrote: “Currently specifications are mostly static documents” — and the agent “can make code changes without updating the specs at all” (Hacker News, July 2025).

4. Nobody knows which spec is current

Five specs touch it. Four are superseded. None of them says which.

— dev.to, September 2026

How do you adress spec drift? A new feature can easily affect 2 or 3 specs. Do you update them manually?

— Hacker News, February 2026

5. Keeping specs in git is not enough

The most-supported request on Spec Kit’s issue tracker, with 115 reactions: “Multiple users find it difficult to update, refine, or iterate on existing specs in Spec Kit without creating new branches and redundant specification artifacts” (github/spec-kit #1191, November 2025). A Kiro user put the reason in a heading: “Why committing specs to git isn’t enough” (kirodotdev/Kiro #9435, June 2026). What git does and does not give a spec: requirements in git.

6. Nobody outside the team can read it

Non-programmers are not used to working with Git. … In practice, they (usually PMs or feature designers) need to write their documents somewhere else.

— Hacker News, March 2026

What a review by non-developers needs is in spec-driven development: who reviews the spec?

What breaks for the people who pay for it

Ranked the same way, from the 202 quotes by agency owners, freelancers, business analysts and product managers.

1. Scope creep, one small change at a time

client kept adding just one more thing and the team kept saying yes without checking with me first.

— an agency project manager, r/projectmanagement, July 2026

Nobody goes back and edits the quote, so the invoice and the thing the client actually approved drift apart and you find out at payment time.

— r/agency, September 2026

2. A sign-off that does not hold

i’ve got the approval emails. i’ve got the call recordings. none of it seems to matter because the relationship feels more important than the paper trail

— r/webdev, March 2026, 136 points and 51 comments. The same post: “Redoing probably 60% of the work. not getting paid for it.”

Each stage has its own version of “what was agreed.”

— r/projectmanagement, July 2026

3. No version is ever closed

I’ve tried email trails. I’ve tried shared Notion docs. Neither of them create a genuine “this version is now closed” moment.

— a web developer who mostly does client work, r/projectmanagement, June 2026

4. Nobody reads it

40 pages, every edge case, traceability matrix and all. technically thorough, completely unreadable for the people who needed to decide.

— r/businessanalysis, June 2026

5. Clients will not log in

The moment they have to sign up for something, they go back to email or WhatsApp.

— r/agency, September 2026

One failure, seen from two sides

1. The specification lives in more than one place. A markdown file, the tickets built from it, the email the client approved, the code. Every copy can be right on the day it is written and wrong a week later.
2. A change tells nothing downstream. A new feature touches two or three specs; a phone call changes the quote; neither marks what it made out of date.
3. The people who have to agree cannot read what they agree to. Developers keep the spec in git, where the client cannot go. Analysts write forty pages the client will not finish.

What people do instead

• Ask an AI to compare the spec with the code, in review or in CI.
• Write “update the docs” into the definition of done — the step that goes first when a deadline comes.
• Delete specs once they are built, and treat the code as the only truth.
• Send a recap email after every call, and keep a decision log in a spreadsheet.
• Add “no reply means approved” to the contract.

What they ask for

• One current specification instead of a pile of snapshots (spec-kit #620).
• A record of what the code looked like when a spec was written, and a warning when it has moved since (Kiro #9435).
• Built work that stays on the record: today “a course correction can silently rewrite the acceptance criteria of a story that was already committed and merged” (BMAD #1930).
• “someplace where anyone can go to see what was signed off on, by who and when.” (r/businessanalysis)

The other side

Plenty of people say specs are not worth keeping.

There is only one source of truth and that is the source code.

— Hacker News, February 2026

“I hated PRDs, so I stopped doing them” drew 172 points on r/ProductManagement in 2024. Solo developers mostly get by with a short notes file and their agent’s plan mode. The complaints come from teams — where the person who answers the questions and the person who skips the update are not the same person — and from agencies, where the person who approves is not in the team at all.

What we take from it

The three failures above are the problems Specroot works on: one specification instead of copies that drift, changes that show what they affect, and sign-off by the people who have to agree. More for teams using AI coding agents and for agencies and consultancies.

Method and limits

• Hacker News counts are exact-phrase matches through the Algolia API, as of 17 October 2026.
• Repository counts come from GitHub’s search API: repositories created in each quarter with “spec-driven” in their name, description or topics.
• Reddit was read through a public archive; its vote counts are snapshots and understate recent posts.
• Rankings reflect where we looked as well as what people said. Read them as an order, not as a measurement.
• Quotes are reproduced as written, including their spelling.