Glossary

Spec-driven development, in the agent sense.

Review the plan, not the pull request. The plan is a page; the pull request is a thousand lines.

Download for macOS
v0.1.33 · .dmg · Apple Silicon & Intel
Signed & notarized by Apple · opens without a Gatekeeper warning
sha256 698955a0187bc039f4c74f5d05a9f10fbb27376a45788a0a241d1326b73873c7
Download for Windows instead
$curl -fsSL https://lucidtrain.com/install.sh | sh

Spec-driven development, in the context of coding agents, means producing an explicit specification of what is to be built, reviewing it, and only then letting the agent implement against it. The point is not documentation. It is that reviewing a specification is far cheaper than reviewing a large diff, and a misunderstanding caught in a paragraph costs a sentence to fix while the same misunderstanding caught in generated code costs a re-read of everything the agent wrote. The specification is a cheap checkpoint, not an artefact to keep.

Why the checkpoint is the value

An agent that misunderstands the task produces a large volume of coherent, plausible, wrong code. Reviewing that is genuinely hard work, because it is internally consistent and reads well. Reviewing a paragraph that says what it intends to do takes a minute and catches the same error before any of it exists. The economics are lopsided enough that the extra step pays for itself on the first miss.

Where it does not pay

For a small, well-understood change, writing a specification costs more than reading the diff. The approach earns its keep when the change is large, when it spans several files, or when the requirements are ambiguous enough that two reasonable people would build different things. Applying it to every change is how teams end up abandoning it.

A diagram is a specification too

A specification does not have to be prose. For structural work, an architecture diagram states the components and their relationships more precisely and much faster to check than the paragraphs describing the same thing. That is the whole argument for treating a drawn architecture as an input to implementation rather than as documentation produced afterwards.

How it relates to plan mode

Most serious agent harnesses ship a mode that explores and proposes without being able to write, which is the same idea enforced by tool gating rather than by discipline. It is stronger than a convention because it does not rely on anyone remembering: the agent cannot skip the specification step, because in that mode it has no writing tools at all.

FAQ

Questions

How is this different from writing a design doc?

Mostly in lifespan and audience. A design doc is written to persist and to inform people. A spec here is written to be reviewed once, immediately, by the person about to run the agent, and is often discarded afterwards.

Does it slow development down?

On small changes yes, and it is not worth it there. On ambiguous or large ones it is faster overall, because catching a misunderstanding in a paragraph beats catching it in a thousand lines.

Is plan mode the same thing?

It is the enforced version. Plan mode removes the writing tools so the specification step cannot be skipped, rather than relying on the discipline to do it.

Related

Last updated