Skip to content

Knowledge base

Spec-driven development

What a written spec changes for an agent, and how a team keeps the spec true while code and tests move on.

Written by

Updated:

Glossary 33

When agents write the code, what people own shifts from the code to the intent. In spec-driven development that intent is a specification: a Markdown file committed next to the code and reviewed in a pull request like any other change. It holds the current state, the change, the patterns to follow, the decisions still open and the acceptance tests, all written before any code exists.

What does a spec change for an agent?

An agent was not in the handover meeting, so everything it needs has to be in a file it can read. Requirements scattered across a ticket, a design file and a conversation reach a person but miss the agent. One spec file gives every later step the same input: refinement, planning, implementation, review and the retrospective. Writing the test cases into the spec first moves test design to the start.

How does the spec stay true?

Route corrections through the spec instead of patching code in chat. Where code or tests drift from the spec, the spec’s owner decides which side changes and writes that decision down. The acceptance tests come out of the spec, and the agent implementing the change neither writes nor edits them. A failing test is a question for the spec’s owner: is the code wrong, or the spec? A schema in the spec pins down the shape of the data, while behaviour lives in acceptance criteria and tests, so passing contract tests proves the shape, not the logic. See Specifications, tests, and context.