Analysis: "A Sufficiently Detailed Spec is Code"

Blog post: https://haskellforall.com/2026/03/a-sufficiently-detailed-spec-is-code

Core Thesis

The post argues that the agentic coding movement's promise — that engineers can simply write specification documents and have AI agents generate working code — is fundamentally flawed. The central claim is captured in the title: if you make a specification precise enough to reliably generate correct code, the specification itself effectively becomes code. There is no shortcut that avoids the hard intellectual work of programming.

---

Structured Outline

1. Introduction (Comic Strip Framing)

• References a well-known comic strip illustrating the absurdity of "just generate code from specs."
• Notes that agentic coding advocates have muddied the waters enough to warrant a deeper treatment.

2. Two Core Misconceptions

Misconception 1: Specification documents are simpler than the corresponding code.

• Agentic coding advocates market the idea that engineers become "managers" who write specs and farm work out to AI agents.
• In reality, making a spec precise enough to reliably produce a working implementation forces the spec to converge toward code — either literally becoming pseudocode/code or highly formalized English.
• Cites Dijkstra's insight: defining an interface doesn't just divide labor — it creates additional work (the work of defining the interface itself). A spec detailed enough to be unambiguous is at least as complex as the code it describes.

Misconception 2: Specification work is inherently more thoughtful than coding.

• Traditionally, writing specs before coding encourages a contemplative, critical lens.
• However, the industry push to reduce labor and optimize for delivery speed undermines thoughtfulness. If spec writing is treated as "easier than coding," the resulting specs will be sloppy and superficial.
• Thoughtful specification work is hard — potentially harder than coding — and current incentives actively work against doing it well.

3. Case Study: Symphony

• Examines a real-world example called "Symphony" — a specification document used to demonstrate agentic coding.
• Points out that Symphony's spec:
  • Contains embedded code/pseudocode, undermining the claim that specs replace code.
  • Reads like AI-generated content (code snippets labeled as text in markdown — a sign the AI was asked to convert code into prose and did so superficially).
  • Is a "grab bag of specification-shaped sentences" lacking coherence, purpose, or understanding of the bigger picture.
  • Would necessarily be slop given the incentives — even if a human wrote it — because the goal is delivery speed over clarity.

4. Conclusion

• Specifications were never meant to be time-saving devices. If you're optimizing for delivery time, you're better off writing code directly rather than going through an intermediate spec.
• "Garbage in, garbage out" — a vague, unclear spec will produce vague, incorrect code. Coding agents are not mind readers.

---

Key Insights

1. The Specification-Code Convergence Principle: There is an unavoidable convergence between sufficiently detailed specifications and code. This is not a new insight (Dijkstra articulated it decades ago), but it gains new relevance in the age of AI coding agents.

2. Specs Add Work, They Don't Remove It: Defining an interface between human (spec writer) and machine (code generator) doesn't simply divide existing work — it creates new work: the work of precisely defining that boundary. This is the fundamental reason spec-to-code promises fail.

3. The Incentive Problem: The current tech industry climate prioritizes speed and cost reduction. This is exactly the wrong environment for spec-driven development, which requires more thoughtfulness, not less. The result is that specs become performative documents rather than rigorous ones.

4. AI-Generated Specs Are Self-Defeating: The Symphony example reveals a circular irony — the spec document itself appears to be AI-generated, meaning AI is being used to write the spec that AI will then use to generate code. This compounds the "garbage in, garbage out" problem.

5. No Substitute for Human Cognition: The post ultimately defends the irreducible role of human engineering judgment. The hard part of software development is thinking clearly about the problem, and no document format or AI agent can bypass that.

---

Critical Nuances

• The author doesn't reject specs entirely. He acknowledges that pseudocode and reference implementations are legitimate tools in specification work. His objection is specifically to the claim that specs replace code.
• The critique targets the marketing, not the tools. The post is less about whether AI coding tools are useful and more about how agentic coding is being sold — with misleading promises that obscure the actual work involved.
• Dijkstra's interface argument is foundational. The post grounds itself in a well-established computer science principle rather than anecdotal complaints, giving it stronger intellectual weight.
• The footnote is revealing: The observation that Symphony's code snippets are annotated as text (suggesting an AI converted a code-heavy draft into a "prose specification") exemplifies how the appearance of specification rigor can be manufactured without substance.