GoKawiilThis 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:
... continue reading