Big Spec Up Front

Also known as

Big Design Up Front, spec waterfall, exhaustive specification.

Context

You work with specs and want the agent to get everything right the first time. So before the first line of code, you and the agent write everything down: states, screens, errors, the data model, edge cases. The agent happily generates text, and the documents grow to dozens of pages.

Problem

Most of the time goes into the spec, and there is still no working version. Meanwhile, a detailed spec doesn't deliver what it was written for. What you actually need becomes clear only when you see the working thing and try to use it. The agent still doesn't follow every instruction, and follows some too literally. Reviewing hundreds of lines of Markdown is harder than reviewing code.

Why people do it

  • A detailed spec gives a feeling of control over the agent.
  • People follow the entire process available in an SDD toolkit regardless of the task's size or uncertainty.
  • The agent writes text fast, so one more section seems to cost nothing.
  • It seems that the more detailed the description, the more accurate the result.
  • There is a fear that without a complete description the agent will go astray.

Consequences

  • ➖ The first feedback from working code arrives in days instead of an hour.
  • ➖ After the first demo a large part of the spec gets rewritten, because the requirements only surfaced on the prototype.
  • ➖ The spec and the code drift apart, and both have to be maintained.
  • ➖ Long documents get skimmed, so reviewing them catches little.
  • ➖ The agent skips some instructions or gets carried away by minor ones.
  • ➖ Small tasks drown in a process that costs more than the work itself.

Signs

  • The spec is longer than the code it will produce.
  • After the first day of work there is no version you can run.
  • You read more Markdown than code.
  • The spec has "just in case" sections nobody asked for.
  • After the first demo half of the spec had to be rewritten.

A better way

Limit the spec to what the agent can't start without: the goal, constraints, acceptance criteria and what is definitely out of scope. Half a page often suffices for a small, reversible change. If a mistake would be costly, agree on constraints and acceptance criteria in more detail. Resolve uncertainty through an early working prototype: a thin end-to-end slice you can run and poke at (see tracer-bullet tickets). From there, edit it based on what you see, and add to the spec what the prototype revealed. That way the spec becomes an outcome of the work as well as an input.

A quick prototype doesn't mean vibe coding. You keep the goal, the criteria and a feedback loop that keeps iterations from breaking what is done. Unlike a throwaway prototype, which answers one question and is discarded, this prototype becomes the first version. Birgitta Böckeler, reviewing SDD toolkits, writes that small, iterative steps are the best way to stay in control, and is skeptical of lots of up-front spec design (article).

Example

Before

Write a complete spec for the subscriptions module: all states, screens, errors, migrations and edge cases

Three days go into forty pages of spec and their review. At the first demo the product manager asks for cancellation to take effect at the end of the paid period, and for the trial not to require a card. The state model and half of the screens get rewritten.

After

Build a working subscriptions prototype from SPEC.md: sign-up and cancellation end to end

SPEC.md is half a page: the goal, constraints from the payment provider, acceptance criteria and what is out of scope for the first version. An hour later the prototype works. You walk through the scenario yourself, show it to the product manager and make edits from the feedback:

Cancellation should take effect at the end of the paid period. Add this to SPEC.md

The spec grows together with the prototype and describes what was actually tested.

results matching ""

    No results matching ""