Why Spec‑Driven Development Gets It Wrong: Augment Code’s Critical Review

Augment Code posted a long article titled “What spec‑driven development gets wrong,” which quickly attracted 260 k reads and sparked intense discussion. The author sees the piece as hitting a widely felt pain point in AI‑assisted programming.

“The only document you can 100% trust is the code itself.”

The article argues that design documents, changelogs, READMEs, architecture diagrams, and onboarding wikis become outdated the moment they are written, a problem the author attributes to human nature—engineers sprint, deliver features, and then abandon documentation as “invisible labor.”

Spec‑Driven Development (SDD) is the target of the critique. SDD’s core idea is to write a detailed specification—requirements, interfaces, edge cases—before an AI agent generates code, which the author acknowledges is better than raw prompts. The failure, however, lies in the second half: the specification itself is a document that inevitably decays.

An outdated design document can mislead the next engineer who reads it.

An outdated specification can mislead an AI agent, which will rigidly follow an obsolete plan and will not indicate where it diverges from reality.

Because agents lack the human ability to “sense something is off,” they will execute blindly, amplifying the risk of stale documentation.

Augment Code proposes a solution called Intent : the spec is no longer a static artifact written solely by humans but a dynamic contract co‑maintained by humans and the agent.

The core mechanism is a workflow:

You describe the desired outcome.

A “coordinator” agent drafts a spec based on the current codebase and splits it into subtasks.

You review, modify, and approve the draft.

The agent executes the tasks; during execution it writes back any new findings to the spec—e.g., discovering reusable components or mismatched API behavior.

You can pause or rewrite any part of the spec at any time, and the agent continues from the updated state.

Example: adding a dark‑mode toggle that follows system preferences. The coordinator agent creates three subtasks (add toggle component, integrate preference storage, update CSS variables). The human notices a missing “cross‑session persistence” item and adds it before approval. While working, the agent discovers an existing Theme Context Provider in the codebase and updates the spec to reflect reuse, so the spec now mirrors the actual implementation without anyone needing to remember to update documentation.

The article notes that documentation decay is an old software‑engineering problem, but AI agents magnify its consequences because they cannot “work around” stale specs the way humans can.

“Intent” introduces a bidirectional maintenance model, contrasting with traditional SDD where the spec is a one‑way input and the agent is a pure executor. This makes the agent act more like a collaborator.

The author raises three reservations: (1) Augment Code is promoting its own Intent product, so the critique may be softened; (2) the signal‑to‑noise ratio of agent‑generated spec updates is uncertain—too coarse a granularity yields guesswork, too fine creates noise; (3) SDD still has value for large, multi‑person projects where upfront architecture and interface contracts are beneficial.

Beyond the specific debate, the piece highlights a broader trend: AI agents are evolving from executors to collaborators, mirroring the software‑engineering shift from waterfall to agile, now with humans and AI jointly adjusting the plan.

“If an agent can write code, it can also update the plan. Let it do that.”

This direction suggests future AI‑programming tools will rely on continuous dialogue and calibration between humans and agents rather than a one‑time perfect specification.