Why Writing Specs Is Just Writing Code Again – The Double‑Watch Dilemma

Many developers imagine that writing a high‑level specification will let AI agents build an entire system automatically, but in practice the spec grows into a second version of the code, complete with bugs and excessive detail.

The author illustrates this by expanding a simple requirement like "the system must support user login" into a cascade of low‑level details: session IDs, token refresh logic, retry strategies, and even schema definitions. These details become pseudo‑code such as

available_slots = max(max_concurrent_agents - running_count, 0)

and retry delay formulas like

delay = min(10000 * 2^(attempt - 1), agent.max_retry_backoff_ms)

, showing how the spec morphs into implementation.

Further examples compare the spec to UML models and ORM mappings, emphasizing that the document ends up describing data structures, API contracts, and service start‑up flows. A concrete snippet demonstrates a service start‑up routine:

function start_service():
    configure_logging();
    start_observability_outputs();
    schedule_tick(delay_ms=0);
    event_loop(state)。

This is effectively code written in a pseudo‑language.

The author then discusses a real experiment where a multi‑thousand‑word spec (named "Symphony") was fed to an AI. Although the generated code ran without syntax errors, it stalled and failed to progress, highlighting the "intent‑understanding gap" between a precise spec and executable logic.

From these observations the author derives the "precision conservation law": any effort to describe a system with higher precision simply transfers that precision from one artifact (the spec) to another (the code), without reducing overall complexity. Vague prompts yield random outputs; precise prompts yield controllable but still fragile results.

Ultimately, the piece concludes that if the goal is fast, reliable delivery, writing code directly is more efficient than over‑engineering exhaustive specifications that become as cumbersome as the code they aim to replace.