Spec-driven development

What is spec-driven development

A specification is a document that says what is to be built before anyone starts writing code. It does not describe each line of code. It gives the goal, the scope, meaning what is part of the work and what is not, and the conditions that must hold when the work is done.

The work runs in three steps:

• Specification. A person writes it alone or with an agent’s help, then reads and corrects it before delivery begins.
• Delivery. A coding agent gets the whole document and works from it. When something is missing from it, the agent should ask, not guess.
• Check. The result is compared with what the specification set out. The work is accepted or goes back for rework.

The specification is a document of its own, not one of the messages in a conversation with the agent. You can correct it, give it to another session or another person, and check a week later what was agreed. When the team changes its mind, it changes the document.

Spec-driven development with AI agents

In agentic coding, where an AI agent takes whole development tasks, the specification is the agent’s task. A short request in a chat leaves a lot open, and the agent settles each open point its own way or stops to ask you. A specification settles those points before the work starts. For an agent it usually holds:

• Goal and scope. Why the work is needed, what is part of it and what is left out, so the agent neither does too little nor changes things along the way.
• Acceptance criteria. Verifiable statements that must hold when the work is done. You judge each one with a yes or a no when the agent reports the work.
• A check the agent runs itself. Tests or a build that end in success or failure, so the agent can check its own work before it reports it.

Size matters too. A specification for an agent should describe one piece of work that a single agent session can deliver whole. Larger work, such as a whole feature described in a PRD, is split into several specifications under one epic, with the order between them written down.

The agent does the work, and a person judges the result: they compare it with the specification and accept it or send it back. This way of working, where a person decides at the points that matter, is called human-in-the-loop. How to write a plan an AI agent can deliver without guessing walks through such a specification step by step, with an example.

Spec-driven development in featureloom

In featureloom the specification is the plan: a markdown document on a kanban board. You write it yourself with the New plan button, starting from an empty document, generate it in the app from pasted text or a PDF or Word document, or ask an agent in a console to write it from your material, such as a meeting transcript you hand it as a file.

A plan generated in the app follows the project’s plan template, and the Planner prompt tells the agent to write plans in that template’s sections. The built-in template asks, among other things, for the goal, scope, steps, acceptance criteria and definition of done. Acceptance criteria are verifiable statements that must hold when the work is done. You fit the template to your team on the Project settings screen, in the Plan template tab.

The command from a plan, such as featureloom realizer INV-14, gives the agent in one call the prompt with your team’s process, the whole plan document and the documents of the delivered plans it directly depends on. The Realizer prompt, which every new organization has, tells the agent to do what the plan asks and nothing more, and to ask instead of guessing when the plan leaves something open. The question and your answer go into the plan document.

At the end the same prompt tells the agent to report the plan delivered with a note: what it did, where it departed from the plan and why, and what it did not do. You compare the result with the plan and choose Accept or Do not accept, with or without reasons. A person gives the verdict, in the app, and the server refuses one sent from a console. After a rejection, the agent reads the verdict and goes back to rework.

A plan can change as the team learns more. Each save that changes the text is a new version, and a plan keeps its last 100 versions. The How featureloom works page shows a plan’s whole road, from the board to acceptance. To see this way of working with Claude Code, from your spec to accepted work, read Spec-driven development with Claude Code.