What is spec-driven development with AI agents?

Spec-driven development is a way of working with AI coding agents where you write down what you want before the agent writes any code, and the agent works from that document instead of from a running chat. A typical spec has three parts: the requirements, a technical plan, and a list of tasks. Tools such as GitHub's Spec Kit and AWS's Kiro walk you through writing each one, with a person approving every step. The idea is sound, because agents do much better on clear tasks than vague ones. The evidence so far says the most valuable part is the acceptance criteria that can be checked, not the length of the document.

Where did spec-driven development come from?

It grew out of the frustration with what people started calling vibe coding, where an agent builds from a conversation and the intent lives only in the chat history.

AWS previewed Kiro in July 2025. It turns a prompt into three files: requirements written as user stories with acceptance criteria, a design, and a task list linked back to the requirements. GitHub released Spec Kit in September 2025 as an open source toolkit that works with several coding agents. Its phases are specify, plan, tasks and implement, with a checkpoint for a person between each. Kiro reached general availability in November 2025 and had been used by over 250,000 developers during its preview.

Birgitta Böckeler's review on Martin Fowler's site sorts the approaches into three levels. In spec-first, the spec is written before the code and may be discarded after. In spec-anchored, the spec is kept and updated as the code changes. In spec-as-source, people edit only the spec and the code is regenerated from it. She found that almost every tool works as spec-first in practice.

Is it just waterfall again?

That is the main criticism, and it has some weight.

François Zaninotto ran Spec Kit on a small feature that displays a date, and got eight files and about 1,300 lines of specification. His argument is that review time roughly doubles, because a person now has to review the spec and the code. Böckeler saw Kiro turn a small bug into four user stories with sixteen acceptance criteria, and wrote that she would "rather review code than all these markdown files". Thoughtworks placed the technique in the Assess ring of its Technology Radar and warned about long spec files that are hard to review.

The fair reading is that writing intent down helps, and writing a lot of it down costs more than it returns. A spec that nobody reviews carefully is just a long prompt.

Does writing a spec make agents more accurate?

Clarity helps. A longer document does not, on the evidence so far.

The case for clarity is strong. A study accepted at ICLR 2026 found that models struggle to tell a well-specified task from an underspecified one, and that resolving the ambiguity through interaction improved results by up to 74% over working without it. Underspecified problem statements were one of the main reasons OpenAI filtered tasks out of SWE-bench Verified. An agent cannot meet a requirement nobody wrote down.

The case for spec documents themselves is weaker. A study of 88,052 pull requests across 119 open source repositories found that, once task complexity was accounted for, pull requests with a linked specification introduced defects at the same rate as those without one. The author's explanation is that people write specs for their hardest work, so a spec signals difficulty rather than adding quality. There is a caveat. The specs in that study were mostly linked issues and tickets, not the output of tools like Spec Kit, so the tools themselves have not been tested this way yet.

METR's review of agent pull requests shows what a spec has to prevent. On its tasks, 38% of agent pull requests passed the tests and none could be merged as they were, most often because of gaps in test coverage. Passing is not the same as done, and a spec that does not say what done means leaves that gap open.

What part of a spec matters most?

The acceptance criteria, written so a check can settle them.

A requirement like "the export should be fast and handle large files" cannot be verified. "When the user exports a project with 10,000 tasks, the file downloads in under five seconds" can. Kiro writes its criteria in EARS notation, a format developed at Rolls-Royce in 2009 that uses a fixed pattern: while a condition holds, when a trigger happens, the system shall respond in a stated way. Given, when and then scenarios do the same job. Both force one trigger and one observable result, so each criterion maps onto a test or a piece of evidence.

This is also where a spec and a definition of done differ. The spec explains what to build and how. The definition of done is the short list of checks that will decide whether it was built. You can have a long spec and still have no definition of done, and then the agent marks its own work as finished. Böckeler noticed this in Spec Kit: its checklists act like a definition of done, but the agent is the one interpreting them.

How do you know whether your specs are working?

Measure how often the first attempt passes. If agents keep failing review on tasks with detailed specs, the specs are long but not clear.

That is what first-pass verification rate measures: the share of agent tasks that pass verification on the first attempt. It is the clearest test of specification quality, because a well-written definition of done passes first time and a vague one comes back. Pair it with the time spent in the spec phase. Long spec time with a high first-pass rate is time well spent. Long spec time with a low first-pass rate is the waterfall problem the critics describe.

How does Cognibl fit with spec-driven development?

Cognibl does not write your spec. You can keep it in Spec Kit, Kiro, a document or the task itself. What Cognibl holds is the part that decides whether the work counts. Each task carries a definition of done, written before the work starts. A status change that completes the task is refused until a proof of work matching the project's template is attached. A reviewer agent can mark each clause of the definition of done as met, not met or cannot tell, and it never reviews its own work. Cycle time is split into spec, build, verify and settle, so the cost of writing the spec is visible next to whether it paid off. See how proof of work is checked.