Why AI-Generated Code Is Flawed: A Detailed Spec Is Already Code

The Allure and Illusion of Specification-Driven Development

The dream is seductive: software engineers evolve from coders to architects, authoring high-level specifications that AI agents flawlessly translate into production-ready systems. This vision of "agentic coding" is being aggressively marketed, with figures like Google's Salva highlighting a shift where developer value lies in "deciding what to build" and "thinking about software at an architectural level." Proponents argue it could be the next generation of outsourcing, simplifying and elevating the engineering role.

However, a deep dive into a flagship example, OpenAI's own Symphony project, reveals fundamental cracks in this premise. The core argument, articulated by programmer Gabriella Gonzalez, is that a specification document detailed enough to reliably generate a working implementation is, for all practical purposes, already code. This challenges two core misconceptions driving the agentic coding movement.

Deconstructing the Symphony "Specification"

OpenAI's Symphony is presented as an agent orchestrator generated from a specification document (SPEC.md). Upon examination, this document is not a traditional, abstract spec but rather "thinly-veiled code." It contains prose dumps of database schemas, explicit algorithms written in structured English, and even literal code snippets labeled as `text` to bypass formatting—a telltale sign of AI generation obeying the letter, not the spirit, of a request.

One section, explicitly labeled a "Cheat Sheet," is admitted to be "intentionally redundant so a coding agent can implement the config layer quickly." This admission underscores the central problem: to make generation reliable, the spec must contort into a pseudo-programming language. As computer science pioneer Edsger Dijkstra noted, attempts at pure verbal precision historically failed until formal symbolisms (like code) were adopted.

Misconception 1: Specs Are Simpler Than Code

The first flawed premise is that specification documents are inherently simpler or cheaper to produce than the corresponding code. The Symphony spec, at roughly one-sixth the length of its Elixir implementation, demonstrates that achieving necessary precision requires immense detail. The spec includes concurrency control logic spelled out in pseudo-code and exhaustive field definitions.

Gonzalez attempted to follow Symphony's own instructions, asking Claude Code to generate an implementation in Haskell. The result was buggy and, even after fixes, produced a non-functional agent. This flakiness isn't unique; even the extensively documented YAML specification, with a full test suite, isn't fully implemented by most parsers. Reliability demands a level of detail that erases any simplicity advantage.

Misconception 2: Specs Guarantee Thoughtful Design

The second marketing pitch is that filtering work through a spec document enforces better engineering practices and more thoughtful design. The reality, as seen in Symphony, can be the opposite. Pushed for delivery speed, specs can degenerate into "AI-written slop"—a grab bag of "specification-shaped" sentences lacking coherence.

An Amazon tech lead emphasizes that "AI lowers the barrier to writing code, but not the responsibility for understanding it." They warn that "creating wrong code is very dangerous" because its mere presence creates a false sense of security. This principle of "garbage in, garbage out" applies directly to specification-driven development. A confused, sloppy spec will not yield a coherent system, regardless of the AI's power.

The Unchanged Core of Engineering Labor

The industry push to devalue labor creates pressure to treat specification writing as a faster, easier alternative to coding. Experts argue this is a fallacy. As the defense industry article highlights, unclear requirements expressed in natural language (like "one good system") are "the worst possible starting point" for a project, leading to vague requirements and program failure.

The Amazon tech lead's "vibe coding" tips reinforce that critical engineering judgment cannot be outsourced. They advise prompting AI with hard questions about fallbacks, scaling, and edge cases—the very same critical thinking required for writing a good spec. The labor isn't eliminated; it's shifted or, if done poorly, compounded.

Gonzalez concludes that specifications were never meant as time-saving devices. The attempt to use them as such, aided by AI, often results in a Borgesian map as large as the territory it describes—a useless artifact. The precision required for software construction demands "narrow interfaces," whether we call them code, structured English, or a specification. The cognitive burden of defining a system with enough rigor for a machine to execute it remains, with or without an AI intermediary.

The Path Forward: Augmentation, Not Replacement

The collective evidence from these sources paints a clear picture. AI is transforming software development, with over half of developers using it for tasks like creating test cases and debugging, as noted in Business Insider. The role is shifting towards higher-level judgment, architecture, and oversight.

However, the vision of engineers merely writing specs while AI does the "work" is a mirage. The real evolution is towards engineers using AI as a powerful tool for iteration and exploration, while retaining absolute responsibility for the final system's correctness and design. The key is not avoiding code, but using AI to navigate its complexity more effectively, all while maintaining the deep understanding that has always been the hallmark of a skilled engineer. The machine cannot yet absorb ambiguity; that burden, and the value, still lies with the human.