Spec-driven development without waterfall

Writing specifications that help coding agents, and keeping those specifications open to correction.

"Administrators can export filtered invoices" sounds like a bounded request. An agent can turn it into an endpoint, a background worker, a download link and a set of tests. Along the way, it must decide what "filtered" means, which version of the data belongs in the file, when permissions apply and what a failed export leaves behind.

Those choices become behaviour that people encounter and other code may depend on. If nobody supplied the answers or bounded the assignment, the implementation has acquired commitments nobody deliberately made.

A specification can be clear, executable and wrong. An agent can implement exactly what it says; tests derived from the same premise can pass; the resulting software can still fail to meet the need that justified building it. A different agent agreeing with the first does not resolve this problem unless the review brings some independent basis for judging the expected behaviour.

The first decision is therefore what work the next question requires: discovery, investigation or a bounded implementation. Four questions guide the later review. They are not successive gates; evidence can challenge a requirement before implementation, during review or after release.

Scroll horizontally to see all columns.

Treat a specification as a maintained contract for a capability. Decide what the next increment must do and what evidence can establish it; leave reversible implementation choices to the implementer. Keep unresolved product questions in the working task and preserve their resolution in history rather than placing them in the current contract. Revisit a settled decision when new evidence challenges its basis, before more work depends on it.

Start with the next consequential question

First, identify the unanswered question that could change what work you undertake next. Sometimes that calls for a specification; sometimes it calls for looking at the system, talking to its users or trying something small enough to discard.

Scroll horizontally to see all columns.

Several of these may apply at once. Start with the question whose answer could prevent the greatest rework or harm from dependent work. Give an experiment a question, a time limit and an observation that would change the decision. Requiring a complete delivery specification before that experiment would demand the very knowledge it is meant to obtain.

An ordinary repair under an existing contract follows a shorter path: identify the applicable requirement, reproduce or investigate the failure, repair its cause, exercise the relevant boundary and record the result. If the requirement remains justified and applicable, repair the implementation and evidence; do not rewrite the contract merely because the code was wrong.

Establish what the existing system actually promises

In an existing system, the temptation is to ask an agent to describe the code and call the result a specification. That description can be useful evidence, but four distinctions matter:

• Observed behaviour comes from executed checks or operational evidence. Conclusions drawn only from code, test definitions or configuration are inferences.
• Required behaviour is an actual promise that should be retained.
• Accidental or defective behaviour has been observed without necessarily being approved.
• Proposed change is the deliberate difference to introduce.

Characterisation tests can retain evidence while intent is resolved. Promoting a generated account of current code directly into an approved requirement can instead give bugs and incidental mechanics the standing of a promise.

For a defect, obtain a reproduction or other credible evidence before deciding to edit the specification. The intended rule may already be right, in which case it can stay. A missing business case requires a decision about the expected result; the existing implementation cannot supply that decision merely by having produced one.

Migrations make this distinction especially consequential. Before dependent implementation, identify what must hold while versions coexist, work remains in flight, data already exists and recovery is under way. Individually correct local specifications can still disagree over shared state. Someone must own the interaction, and its invariant must be explicit.

Decide when to commit without freezing discovery

A large delegated assignment can turn one unanswered question into many dependent implementation choices before anyone reviews the first. Exposing a question, investigating it and committing to an answer remain three different acts; treating them as one can freeze discovery before the evidence warrants a decision.

For invoice exports, exposing the question means recognising that access revocation might affect downloads. Acquiring evidence means examining user expectations, existing contracts and technical feasibility. Committing means adopting a guarantee that both the implementation and its consumers may rely on. The more expensive that guarantee will be to reverse, the earlier its basis deserves investigation. The commitment itself should follow when the evidence and dependencies justify it.

Deadlines sometimes force decisions while uncertainty remains. Record the assumption and its consequences. A deadline changes the time available to decide; it does not turn an assumption into a fact.

Fowler’s January 2026 commentary emphasises experimentation and feedback in specification, while Agile’s principles support frequent delivery and changing requirements. These sources support feedback-oriented practice; they do not establish a universally optimal planning horizon.

Match detail to the commitment

A project needs enough direction to make local work coherent, and an increment needs enough precision to be implemented and assessed. Specifying distant possibilities as precisely as imminent work makes it harder to tell which decisions are settled enough for other work to depend on.

Scroll horizontally to see all columns.

A small increment handling private data needs its isolation rules now; a high-risk consistency decision may need a model before any implementation. The relevant measure is the consequence of being wrong, not the apparent size of the feature.

For each consequential unresolved question in the working record, retain the evidence, its owner, the work depending on it and the event that should resolve it. When an agent reaches that dependent work, the available choices are to resolve the question, exclude the work or authorise a bounded experiment. Leaving the answer blank must not silently grant authority to decide the product’s behaviour.

Preserving an option often means leaving a capability unimplemented. A generic interface, plugin system or configurable framework is itself a set of design commitments. Uncertainty alone does not justify one.

Revisit decisions as you build and use the software

The loop distinguishes investigation, commitment, implementation, release and observation. An accepted investigation returns findings to the next decision; release follows acceptance of a delivery increment. New evidence reopens the affected decision. It need not restart the project, and it may end by removing a proposed feature altogether.

Patton describes discovery and delivery as concurrent work involving the same team, and warns against separate teams handing off finished decisions. The same concern applies when the division is between a planning agent and an implementation agent: the assignment must retain a route for questions and discoveries to change the proposed work.

Waterfall risk grows as commitments accumulate faster than feedback can change them. Dividing implementation into short sprints cannot fix a process that specifies the entire product upfront and then treats discoveries as deviations. The next increment needs a precise contract, with a way to revise it when its basis fails.

Evidence and limitations

Evidence and guidance: clarification and repository guidance, specification history, and assessing automation cost.

These recommendations are engineering judgements, not a complete method validated by the research cited across the series. The evidence addresses narrower questions; it establishes no universal specification length, mandatory template or productivity gain. The examples here are hypothetical, and no development experiment was run for this article.

The BDD, Agile and dual-track sources describe methods and feedback cycles. Spec-Driven Development for Agentic Software Engineering: Harnessing Human-Agent Teamwork is a conceptual framework that calls for empirical validation.

When the evidence makes implementation the next action, commit to a bounded behaviour rather than a complete product plan. That behaviour needs a contract. Part 2: Writing specifications for coding agents shows how to write it while leaving later decisions open.