A sufficiently detailed spec is code

This post is essentially this comic strip expanded into a full-length post:

For a long time I didn't need a post like the one I'm about to write. If someone brought up the idea of generating code from specifications I'd share the above image with them and that would usually do the trick.

However, agentic coding advocates claim to have found a way to defy gravity and generate code purely from specification documents. Moreover, they've also muddied the waters enough that I believe the above comic strip warrants additional commentary for why their claims are misleading.

In my experience their advocacy is rooted in two common misconceptions:

• Misconception 1: specification documents are simpler than the corresponding code. They lean on this misconception when marketing agentic coding to believers who think of agentic coding as the next generation of outsourcing. They dream of engineers being turned into managers who author specification documents which they farm out to a team of agents to do the work, which only works if it's cheaper to specify the work than to do the work.
• Misconception 2: specification work must be more thoughtful than coding work. They lean on this misconception when marketing agentic coding to skeptics concerned that agentic coding will produce unmaintainable slop. The argument is that filtering the work through a specification document will improve quality and promote better engineering practices.

I'll break down why I believe those are misconceptions using a concrete example.

Thinly-veiled code

I'll begin from OpenAI's Symphony project, which OpenAI heralds as as an example of how to generate a project from a specification document. The Symphony project is an agent orchestrator that claims to be generated from a "specification" (SPEC.md), and I say "specification" in quotes because this file is less of a specification and more like pseudocode in markdown form. If you scratch the surface of the document you'll find it contains things like prose dumps of the database schema, concurrency control logic, and even reference algorithms written in a language-agnostic function style.

I feel like it's pretty disingenuous for agentic coding advocates to market this as a substitute for code when the specification document reads like code (or in some cases is literally code). Don't get me wrong: I'm not saying that specification documents should never include pseudocode or a reference implementation; those are both fairly common in specification work. However, you can't claim that specification documents are a substitute for code when they read like code.

The Paradox of Precision

If you try to make a specification document precise enough to reliably generate a working implementation you must necessarily contort the document into code or something strongly resembling code (like highly structured and formal English).

A short look at the history of mathematics shows how justified this challenge is. Greek mathematics got stuck because it remained a verbal, pictorial activity. The modern civilized world could only emerge when we freed ourselves from the fetters of verbal precision thanks to the consciously designed formal symbolisms. Agentic coders are learning the hard way that you can't escape the "narrow interfaces" (read: code) that engineering labor requires; you can only transmute that labor into something superficially different which still demands the same precision.

Flakiness

Also, generating code from specifications doesn't even reliably work! I actually tried to do what the Symphony README suggested: I asked Claude Code to build Symphony in Haskell according to the spec, and it did not work. This highlights that despite the hype, the gap between a natural language description and a functional system remains significant.