Spec-Driven Development

The spec pays for itself

Nobody ever loved writing requirements, and the spec is not beloved either. But the economics changed underneath the dislike. When delivery time for a unit of work approaches zero, ambiguity becomes the most expensive thing in the system. An hour on the spec saves roughly ten hours of rework downstream, and AI makes that ratio worse if you skip it, because a fleet turns ambiguity into an entire wrong implementation before lunch, and someone has to unwind it.

Speed of production raises the cost of ambiguity. The spec is how you pay that cost down before it compounds.

The spec is a testable contract, written before the build. It is not a requirements document. It is not a user story with acceptance criteria stapled on. It is the only artifact where intent becomes checkable before anything is built.

The authorship split: Spec Agent drafts, Decision Owner signs criteria, Domain Expert validates
The authorship split: Spec Agent drafts, Decision Owner signs criteria, Domain Expert validates

The user story and the requirements document

The user story and the requirements document, and each fails the daily cycle differently.

The user story was designed for a two-week sprint. The narrative was useful for conversation but useless for machine execution, the criteria were usually written after the story was sized, so they reflected the estimate rather than the intent, and "acceptance" happened at sprint review as a demo-based approval.

The requirements document was designed for a waterfall handoff. Exhaustive, produced by one group, handed to another, stale before the build started, and still wrong, because requirements gathered in advance never survive contact with the build.

The spec replaces both by being short (one page), daily (written every day), checkable (every criterion can be verified in the harness), and owned by the person who accepts the work (the Decision Owner). And it names the outcome to reach without prescribing the solution.

Inside a one-day spec

One increment, roughly five to fifteen acceptance criteria, one page. If it does not fit on a page, it is two specs. If it has more than about fifteen criteria, the fleet cannot complete and prove it in a single build day, and you end the day with a partial increment and no clean acceptance decision.

A complete spec includes:

  • The outcome this increment serves, in one sentence, traced to the Now horizon
  • What exists already, so the fleet does not rebuild it
  • The behavior being added or changed, stated as "when X, then Y" so each clause becomes a check
  • Acceptance criteria, each independently checkable, each signed by the Decision Owner
  • Constraints and policy the increment must not violate
  • Explicitly out of scope, which is the cheapest defect prevention available
  • The open questions the owner expects to answer during the day

The authorship split

Forty-five to ninety minutes of the Decision Owner's day, and not from a blank page.

The spec agent drafts. Structure, restated context, proposed criteria from the outcome brief and prior increments, and flags for what it does not know. A usable draft arrives in minutes.

The Decision Owner corrects and signs. They fix what the agent got wrong, delete the noise, add the constraints only a domain person would know, and personally approve every criterion. The criteria are the one part they must author in substance, because the criteria are the judgment.

The domain expert validates. A member of the Domain Knowledge Network spends fifteen minutes reviewing the criteria that touch their specialty. Correctness, not style.

If the owner is spending three hours, one of three things is wrong. The slice is too big, they are typing prose a machine should draft, or the Flow Council handed down a brief that was not decision-ready. The governing ratio: if the Decision Owner is typing more than they are deciding, the balance is wrong.

The day-ahead tension

Here is the objection every team raises, and it deserves a straight answer. The spec runs a day ahead so the build day starts ready. But the owner often does not know what they want next until they have seen today's demo. Those two facts appear to contradict each other. They do not, for three reasons.

Most of tomorrow's spec is already known. The stable part, the outcome, constraints, policy envelope, data model, and the general shape of the next several increments, is written days or weeks ahead and changes rarely. It is 70 to 80% of the spec's substance. The demo informs the volatile 20 to 30%: which slice comes next and its exact criteria. Daily planning is a small delta decision against a mostly-written contract, not authorship from scratch in twenty minutes.

The buffer is a queue, not a fixed lead time. Keep one to three candidate specs ready. Most days the demo confirms the direction and you pull the next one unchanged. Some days it surprises you and you reorder or amend. A queue deeper than three is a backlog forming, and it means you are speculating past your learning rate. The Confirm, Amend, or Replace call that daily planning makes is covered in the one-day cycle, and the Replace rate is your diagnostic: persistently above 30%, slice smaller; persistently at zero, question whether the work needed this model.

When you do not know, spend a cycle finding out. Replace days are not failures. They mean you learned something expensive early, which is the point of shipping daily. When the new direction is unclear, run tomorrow as a spec-and-explore cycle. The day still ends with something in someone's hands, but the artifact is a decision rather than an increment. This is the learn branch of ship-or-learn.

If every demo overturns the plan, your slices are too big. A demo that invalidates a week of planned work means you planned a week ahead of your knowledge. A demo that adjusts tomorrow means you sliced correctly.

How the spec connects to the harness

Every "when X, then Y" in the spec becomes a check in the harness. This is not a metaphor. The flow runs in one direction: the owner writes the criteria, the spec agent structures them as checkable statements, the harness expresses them as automated checks, the checks run on every push, and the owner accepts against the evidence.

At no point does the implementation inform the criteria. The Fleet Lead's most important review is confirming exactly that, because a harness whose checks trace to the implementation rather than the criteria is green and meaningless.

This one-way flow is also why speed makes the spec more important, not less. A testable contract bounds the amplification. It tells the fleet what to make, the harness what to prove, and the owner what they will be asked to judge. The spec is complete when those three readings agree, not when the document reaches a prescribed length.

The failure modes

The rework math: without a spec 40% of time is rework, with a spec rework drops below 5%
The rework math: without a spec 40% of time is rework, with a spec rework drops below 5%

The spec as afterthought. The team starts building from a conversation while the spec is still open. By 4pm the criteria are final but the fleet built against assumptions, half the criteria do not match the implementation, and acceptance becomes a negotiation about what was meant rather than a judgment against evidence.

The three-hour spec. The owner types prose from scratch, the build day starts at noon, the harness is thin, the demo is weak. The problem is not the owner's speed. It is the absence of the spec agent.

The uncheckable criterion. "The user experience should feel intuitive." There is no check for intuitive, the Fleet Lead cannot tell the fleet what it means, and at 4pm the owner says "that is not quite right" without being able to say what is wrong. The correction is the checkability test, and it takes thirty seconds per criterion: can I write a check for this? "A request above $50,000 for this product type is rejected" passes; the harness submits $50,001 and confirms the rejection. "Feels intuitive" gets rewritten as behaviors: "the form pre-fills the customer's name from the previous screen, the submit button is disabled until required fields validate."

Scope grows during the day. The fleet discovers the spec implies more than a day can absorb. Split the increment, land what is provable today, carry the remainder into tomorrow's spec. Extending the day sets a precedent for variable-length cycles, and the discipline erodes within two weeks.

The drifting spec agent. Spec agents learn from previous increments, and over time they drift toward proposing criteria that match the implementation pattern rather than the business intent. The owner catches this by reading every criterion against one question: is this what I need to be true, or what was true last time?

Its place in the Model

In The AI-Native Operating Model™, Specify is Step 4 in the work lifecycle, sitting at the boundary between direction (blue) and domain judgment (green). The spec is where strategy becomes executable and where domain knowledge becomes checkable.

The spec connects to:

Read the Spec-Driven Development white paper (PDF). Return to the Model to see how the spec connects to the rest of the system.