Spec-driven development, and what happened to it
The definition, the tools, the people who tried it and stopped, and the problem that was still there when they stopped.
Where this comes from
Quotes are verbatim from three public Hacker News threads: the November 2025 discussion of "Spec-Driven Development: The Waterfall Strikes Back", the February 2026 "Ask HN: Are you still using spec driven development?" and the August 2026 "Ask HN: What Happened to Spec-Driven Development?". Tool descriptions are from each tool's own documentation as of September 2026 and are argued at length on the comparison pages. The locking behaviour described is services/llm_jobs.py in our own codebase. We have not measured how often an agent deviates from a written spec, or how far a CLAUDE.md drifts over twenty sessions; that measurement is running and will get its own page rather than a number here.
What spec-driven development is
Spec-driven development (SDD) is a way of working with AI coding agents in which a written specification (what the software must do, the constraints it must respect, and the criteria for calling it done) is produced and reviewed before any code, and the agent implements against it. The specification, not the chat transcript and not the code, is the artifact you maintain. When the spec and the code disagree, the spec is what gets fixed first.
Every tool in the category shares one loop: describe the change, turn the description into a plan, turn the plan into tasks, implement the tasks, with a person reviewing between steps. What differs is where the spec lives and who is allowed to touch it.
| Tool | Spec lives in | Unit | Who can change it |
|---|---|---|---|
| GitHub Spec Kit | spec.md, plan.md, tasks.md | a change | anyone, agent too |
| Kiro | requirements.md, design.md, tasks.md | a feature | anyone, agent too |
| OpenSpec | openspec/specs + openspec/changes | a delta | anyone, agent too |
| BMAD | files passed between personas | a project | agents, by convention |
| Tessl | a registry, or spec-as-source | a library / a system | Tessl, or you |
| A plain plan.md | the working tree | a change | anyone, agent too |
The tools are compared one at a time, with where each beats us, on the comparison pages. This table is only the shape.
Why it appeared
Vibe coding (prompt, accept, prompt again) produces a working prototype faster than anything before it and then, a month or two in, stops producing anything you can trust. The failures are specific and we have written them up from people's own accounts in the vibe-coding wall: no source of truth, features you cannot safely add, code you no longer understand, an agent that guesses. All of them come from the same place: the agent had nothing to be grounded to except the code and the last few messages.
Author thinks about specs as waterfalls. I think about them as a context entrypoint for LLMs.
podgorniy, Hacker News, November 2025
I found that having a work methodology similar to spec-driven development is much better than vibe coding. The agent makes less mistakes, it stays on the path and I have less issues to fix.
DeathArrow, Hacker News, November 2025
That is the whole pitch, and it is correct as far as it goes. GitHub shipped Spec Kit, AWS built Kiro around the idea, OpenSpec and BMAD grew large communities, and for about six months the question was which one to pick.
What happened to it
By February 2026 the question on Hacker News had changed to whether anyone was still doing it.
Question was prompted by seeing spec kit have no commits for over a month an no obvious integration with GitHub's new agents integration.
cherry_tree, "Ask HN: Are you still using spec driven development?", February 2026
For a minute, it seemed like SDD tools like Kiro, OpenSpec/SpecKit, Tessl were gonna be the future of coding agents.
vivekyyy, "Ask HN: What Happened to Spec-Driven Development?", August 2026
Read both threads end to end and the reasons people give for stopping are three, and they are consistent.
The spec does not determine the code. Two runs from the same spec produce two different programs, so the spec cannot be the thing you trust:
the spec is not comprehensive enough to guarantee one specific implementation. If the spec really did translate one-to-one then the spec would really become a higher level language
vivekyyy, Hacker News, August 2026
As much as no one wants to read the code anymore, it seems like most people seem to agree it's the only source of truth.
mikgp, Hacker News, August 2026
The models got good enough that a plan file does the job. The ceremony of a four-phase workflow stopped paying for itself on ordinary changes:
Agents are already too good, the models improved. Nowadays you can just start with a plan.md and add everything you want there
thiago_fm, Hacker News, August 2026
Writing the spec was the hard part, and the tools made it harder. This one shows up in every thread, usually from people who wanted it to work:
I found the many many hours—tweaking, asking, correcting, analyzing, adapting, refining, reshaping, etc—before getting to see any code challenging.
thomascountz, on trying Spec Kit, Hacker News, November 2025
I tried SDD, consciously trying to like it, but gave up. I find writing specs much harder than writing code, especially when trying to express the finer points of a project.
zvr, Hacker News, November 2025
the thing to notice
Every one of these is a complaint about the spec as a document: a file that is too long to write, too loose to trust, and too much ceremony to keep. None of them is a complaint about the idea that the agent should be building to something you decided.
The complaint that did not go away
The same August thread that declared the tools over opened with the reason they existed, still unsolved:
coding agents still improvise code that doesn't fall under the user's requirements all the time.
vivekyyy, Hacker News, August 2026
Agents are getting very good also on inventing features. Features that the dev might even like, or might just ignore they exists...unless looking at the code or asking the agent specifically.
2dera, Hacker News, August 2026
what I think we all know is you have to tell an agent over and over how to get the right answer or it will deviate.
ErrantX, Hacker News, November 2025
We have two pages on exactly this: why an agent guesses requirements when the prompt leaves a gap, and an incident in our own repository where an agent "fixed" behaviour that was deliberate because nothing recorded that it was. Neither failure is cured by a plan.md, because both happen in the space between what the file says and what the agent decides.
What is actually happening. The spec the tools produce is a file in the working tree. That has three consequences the threads describe without naming. The agent that reads the spec can edit the spec. Ask it to "update the spec to match" and it will, and it will also do it unasked. The spec describes a change, so next session it is history, and the only thing that persists is a prose file the agent re-reads from scratch. And nothing in a markdown file distinguishes a rule you decided from a rule the model filled in, so the two accumulate together and drift together.
Specs are great to identify what has been implemented without explicit control, and to get control over it - if needed.
2dera, Hacker News, August 2026
That is the part worth keeping. The tools that faded were workflows for producing a document. The need they answered, something the agent is held to and you control, is the same need it was in 2025.
Is it waterfall?
The November 2025 article that framed SDD as "the waterfall strikes back" got the most useful pushback in the thread under it, from both directions.
the problem with waterfall wasn't the detailed spec, it was a) the multi-year lead time from starting the spec to getting a finished product b) no (cheap) way to iterate or deliver outside the spec. Neither of these are a problem with SDD.
4ndrewl, Hacker News, November 2025
The problem is the same for SDD, as soon as you want quick changes you have to abandon the spec.
constantcrying, Hacker News, November 2025
Both are right about something. A spec is waterfall exactly when changing it is expensive, which is when the unit is the whole project and a change means re-deriving the document. It stops being waterfall when the unit is a single requirement: this rule is decided and locked, that one is still open, the third changed last week and the story that depends on it is flagged. Per-feature spec files get halfway there. Per-requirement objects with links between them get the rest of the way, and that is a data-structure decision, not a methodology one.
What works without us, and how far it gets you
A CLAUDE.md or AGENTS.md. One file, loaded every session, version-controlled with the code. For one person on one repository this is the whole answer, and the practitioners in these threads are clear that the file, not the toolkit, is the load-bearing part:
You don't need spec kit or humanlayer per se, though they are good reference points for starting out, but you do need your own CLAUDE/AGENTS, README, ARCHITECTURE, SDRs, policies, research docs and planning docs all nicely organized in files and folders to work well with AI agents. … I find the sweet spot is ~750 lines for each file.
waldopat, Hacker News, February 2026
Where it stops: the agent can rewrite it, nothing tells you when it drifted from the code, and a paragraph cannot be traced to the story it came from. The comparison with CLAUDE.md goes through each.
Plan mode and a plan.md. Have the agent read before it writes, produce a plan, and let you edit the plan. This is most of Spec Kit's loop by hand, at no ceremony cost, and for a change that fits in one session it is enough. Where it stops: the plan is gone next session, and the questions the agent should have asked are only the ones it thought of. The Claude Code guide shows the loop and the edges.
Spec Kit or OpenSpec for a feature. Worth the overhead on a feature with real scope, expensive on a one-line fix; Spec Kit's own docs say it is a poor fit for small scripts. Where it stops: the spec is per change, and the agent that implements it can also edit it.
Tests as the spec. Capture the requirement as a test and the agent cannot argue with it. This is the strongest grounding available and we recommend it on every page we have. Where it stops: a test says what the code does, not why, and not what was decided and never coded. The manager-approval-above-200 rule that has not been implemented yet has no test to fail.
Once specs are captured as tests, the LLM can no longer hallucinate. I model this as "grounding".
survirtual, Hacker News, November 2025
What a spec has to be, for the complaint to go away
Take the three failures of the file and invert them, and you get the properties a spec needs if the agent is to be held to it rather than merely shown it.
- Persistent. The spec is the primary object next session, not a file the agent re-reads and re-interprets. What the project is, not what this change was.
- Governed. A requirement you have decided is not in the model's input when it regenerates. Not "please do not change this" in a prompt, but excluded from the set it is given. In our codebase that is one line:
chosen_reqs = [req for req in existing_reqs if not req.lock]. - Explicit about what is undecided. The questions the description leaves open are listed as open, so the model records a gap instead of filling it. That is the difference between deciding a rule and discovering the model decided it for you.
That is what Entalpa is: a spec-driven development platform where the specification (stakeholders, needs, user stories, requirements, design) is a store served to your agent over MCP, with locking and open questions built into the objects rather than the prompt. It is not a workflow and does not replace Spec Kit, OpenSpec or your CLAUDE.md; those decide how the agent works, this holds what the product must do, and they compose. It connects to Claude Code, Cursor, Codex and any other MCP client, and reading or writing the spec over MCP never spends credits.
the short version
Spec-driven development did not fail. The spec-as-a-markdown-file did, for the reasons its own users gave. The agent still improvises outside the requirements, so the requirements have to be somewhere the agent cannot improvise.
Questions this raises
Is spec-driven development dead?
The tools that packaged it as a four-phase markdown workflow have lost momentum, and two Ask HN threads in 2026 asked why. The practice, deciding what the software must do before the agent writes it and holding the agent to that, is what everyone in those threads still does, with a plan.md, a CLAUDE.md, or tests. What faded is a document format, not the idea.
Spec-driven development vs vibe coding: which should I use?
Vibe code the prototype; you cannot write a spec for something you have not seen yet. Switch when the project is bigger than your head, when you stop being able to say what a change will touch. The failures that appear at that point are described, in users' own words, in the vibe-coding wall guide.
Is a markdown file enough, or do I need a tool?
For one person on one repository, a CLAUDE.md or AGENTS.md is enough and anything more is overhead. You need something else when the file has been rewritten by the agent, when a rule has to survive the session, or when you need to know what a rule affects, which is traceability that prose does not have.
What is the difference between a spec and a CLAUDE.md?
A CLAUDE.md tells the agent how to work in this repository: conventions, commands, style. A spec says what the product must do: the requirements, who they came from, and which are decided. Keeping them apart is what lets you lock the second without freezing the first.
Is spec-driven development just waterfall?
Only when changing the spec is expensive. Waterfall's problem was the lead time and the cost of iteration, not the existence of a spec; a spec that changes per requirement, in minutes, with the agent implementing the delta, has neither problem.
Entalpa gives your agent one locked source of truth
Structured, traceable requirements your agent reads over MCP — so it works from a curated spec instead of reconstructing your project every session. Free to start, no card, and MCP calls never spend credits.