Spec-driven development: who reviews the spec?
Spec-driven development means writing the specification first and having an AI coding agent build from it, so the spec — not the chat — is the source of truth. In the popular tools, the person who reads and approves that spec is the developer who will build it. When the people who have to agree are not developers — a client, a product owner, a compliance reviewer — the spec needs a different kind of review.
What spec-driven development is
The workflow is the same across tools: describe what you want, turn it into a spec with requirements and acceptance criteria, derive a plan and tasks from it, and let the agent implement the tasks. GitHub’s Spec Kit, OpenSpec, Kiro and the BMAD method are the best-known (how they compare); new repositories built around the idea went from 10 a quarter in early 2025 to 2,504 in the third quarter of 2026 (our count).
Birgitta Böckeler describes three levels of the practice:
| Level | What it means |
|---|---|
| Spec-first | A spec is written first and used for the task at hand |
| Spec-anchored | The spec is kept after the task, and used to evolve and maintain the feature |
| Spec-as-source | The spec is the main source; people edit only the spec, never the code |
The loop step by step, with an example and the criticism: what is spec-driven development.
Who reviews the spec today
In Spec Kit, OpenSpec, Kiro and BMAD the spec is a set of markdown files, written with the agent, in the repository or the editor. In practice the reviewer is the developer running the agent. The Thoughtworks Technology Radar noticed the gap in November 2025:
some generate lengthy spec files that are hard to review, and when they produce PRDs or user stories, it’s sometimes unclear who their intended user is.
— Thoughtworks Technology Radar
Why a developer’s review is not enough
The people who have to agree cannot read it there.
Non-programmers are not used to working with Git.
— Hacker News, March 2026
Tech specs often require comments, discussion, or estimate/budget approvals from non-tech staff.
— Hacker News, March 2026
Of one popular framework, a developer wrote: “Not something you’d give to a business person” (Hacker News, September 2026).
There is too much to review well. A developer whose company adopted OpenSpec: “every change, medium or larger, turns into a large set of multiple markdown documents, each that need review” (Hacker News). Marmelab found that with spec-driven development “review time doubles” (Marmelab).
A developer and a client answer different questions. A developer approves what can be built. A client approves what should be built — and what it costs. A compliance reviewer approves what is allowed.
the spec doc has to be readable by people who can’t read code. That’s actually the whole point of putting it next to the code instead of in Confluence - if your compliance reviewer or your business analyst can’t audit the same artifact your engineer implements against, you’ve just moved the alignment problem one layer down.
— a commenter writing about financial services, r/ProductManagement, May 2026
What a spec review needs that a code review does not
| Aspect | Code review | Spec review |
|---|---|---|
| Who reads it | Developers | Everyone who has to agree: the client, the product owner, compliance, the team |
| What it shows | A diff of files | What changed in the requirements since they last approved |
| What language | Code | The reader’s level: business intent for the client, technical detail for the team |
| The question | Does it work, and can we maintain it? | Is this what we want, and what else does it change? |
| The decision | Merge | Sign-off on one version, recorded with who and when |
| Afterwards | The merge is the record | The approved version stays readable while work continues |
How to add a non-developer review to spec-driven development
- Split the spec by reader. Business intent and acceptance criteria in the client’s language; the technical plan separately. One giant spec file serves nobody.
- Get the business part signed off before the plan is generated, when changing it is cheapest. The same commenter works this way: “the source-of-truth file gets written down, reviewed, signed off, and only then handed to the agent for implementation.”
- Review differences, not documents. Show what changed since the last approved version, not the whole file again.
- Record the decision against a version — who, when, which version. The requirements sign-off template does this on paper.
- Treat later changes as change requests, with their impact shown first — see change request vs pull request.
- Pin the work to the approved version, so that when the spec moves, the work built from it says so. Otherwise you get spec drift.
Git can carry the audit trail — “Every status change, edit, approval is a commit with an author and timestamp”, as the same commenter put it — when every reviewer works in git. When the client does not, the review has to happen somewhere they can read — see what version control does not track. The product manager’s side of it, with a ten-minute review of an agent-written spec: spec-driven development for product managers.
Spec-driven development vs vibe coding, and vs TDD
Vibe coding describes what you want as you go and accepts what the agent produces; nothing lasting is written down. Spec-driven development writes the intent down first and keeps it.
Test-driven development writes tests first: executable specifications of behaviour. A spec also holds what a test cannot — why, who agreed, what is out of scope. The two combine: the acceptance criteria in the spec become the tests.
Does spec-driven development work?
The criticism is real. Marmelab: “Big Design Up Front has proven to fail most of the time”. On Hacker News: “There is only one source of truth and that is the source code” (Hacker News). And specs that are not maintained drift away from the code — one of the three complaints we found most often about these tools (what 20,000 comments say).
A spec earns its cost when someone outside the development team has to agree with it, or when the work outlives the session that produced it. For a one-off feature built by one developer, a short plan in the agent may be all that is needed.
Where Specroot fits
This is the problem Specroot works on: a spec review built for the people who have to agree, not only for the developer running the agent. Specroot for teams using AI coding agents.
Read next
- Spec Kit vs OpenSpec vs BMAD: what each leaves out — Spec Kit, OpenSpec and BMAD compared, with Superpowers, Kiro and GSD: how each works, what users say about it, and the gaps all of them share.
- Spec template for spec-driven development (spec.md) — A free spec.md template for spec-driven development with Claude Code, Cursor or Copilot: what goes in a spec, an example, and spec.md vs CLAUDE.md.
- Spec-driven development on an existing codebase — How Spec Kit, OpenSpec, Kiro and BMAD work on an existing codebase: specify the change, not the system. What that leaves out, and how to start.