Skip to content
Module
AI

What is spec-driven development? A PM's guide

Spec-driven development is a way of building software with coding agents in which the written specification is the reference everyone works from. You first describe the intent, the expected behavior and how to verify it, then the agent derives a plan and a task list before touching any code. The spec lives in the repository and evolves with the product rather than being forgotten after launch.

Definition written by Alex Dionisio, Senior Product Manager. Updated November 13, 2026.

Why it matters for a PM

A coding agent quickly carries out whatever it is asked, vague requests included. The faster code generation gets, the more the quality of the spec determines the outcome. That puts the PM, who owns the intent and the business rules, back at the center: a sharp spec cuts down rework, makes the agent's plan reviewable and gives everyone a shared definition of finished.

Example

For an invoice export feature, the PM writes a spec file covering the user problem, the required formats, the cases where export must be refused, and a list of testable criteria. The agent proposes a six-step plan. Reading it, the PM realizes canceled invoices were never mentioned, updates the spec, and the agent regenerates its plan before writing a single line.

What does a spec-driven cycle look like?

The cycle moves through stages that are approved one at a time. First you write what the feature must do and for whom, along with its acceptance criteria. The agent derives a technical plan from that: affected components, data, dependencies. The plan is then broken into small tasks, which the agent carries out in order, checking each one. A human reviews every stage before the next begins, which is far cheaper than fixing code that has already been written.

Public tools follow this pattern with their own vocabulary. Spec Kit, open-sourced by GitHub, chains commands to specify, plan, break down into tasks and implement, and relies on a document setting out the project's principles. Kiro, the AWS environment, produces three files: requirements, design and a task list. Nothing stops a team from applying the approach with plain Markdown files and whichever agent it prefers.

For a PM, the most valuable moment is the review of the plan. Reading it, you can catch a forgotten business rule, a scope that has quietly grown or a technical choice that will constrain the roadmap, all before a single file changes. That review takes minutes, while unpicking the same mistake in finished code can take days.

Spec-driven development vs PRD vs TDD: what is the difference?

A PRD is written primarily for people: it justifies an investment, sets the scope and aligns teams. A spec written for an agent goes further into verifiable detail: expected behavior case by case, technical constraints, sample data, a definition of done. The two complement each other, and part of the PRD can feed straight into the spec.

Test-driven development (TDD) works at another level: you write a failing test before the code that makes it pass. It fits well with spec-driven development, because the acceptance criteria in the spec translate naturally into tests. The real opposite of the approach is vibe coding, where you chain conversational requests with no reference document. That works for a throwaway prototype and is risky for a product meant to last.

When is the approach worth the effort?

It pays off on features dense with business rules, on projects where several people and several agents contribute, and wherever someone will later need to explain why the system behaves the way it does. For a one-line fix or a prototype meant to be thrown away, it mostly adds ceremony.

A few questions help a team get started. Who writes the spec, and who approves it? Where does it live, and how do you know it still matches the code? What does the agent do when the spec says nothing about a case: stop and ask, or decide alone? Keep the main limitation in mind as well: a spec guarantees nothing by itself, and the agent can drift from it. Code review and tests remain the final proof.

Key points

  • The spec covers the what and the why; the agent proposes the how, which the team reviews before execution.
  • Testable acceptance criteria let the agent and the humans judge the result the same way.
  • Public tools support the approach, such as GitHub's Spec Kit or AWS's Kiro environment.
  • An outdated spec becomes a trap: it has to change whenever the code does.

Common mistakes

  • Writing a very long spec nobody reads instead of a short, testable one.
  • Letting the agent invent business rules the spec leaves out without getting them approved.
  • Assuming a good spec removes the need to review the code and test real behavior.

Go further with Module

The courses and lessons that cover this concept:

Guides on this topic