Spec-Driven Development Is Nonsense

We already have a language for describing software precisely enough to execute it. It is called code.

Natural language serves a different purpose. It can explain why a product should exist, what outcome it should create, which constraints matter, and how we will judge success. It cannot describe every implementation detail without ambiguity. There is no need for it to do so.

Once a specification tries to prescribe the complete implementation, it becomes an ambiguous and less testable rewrite of the code we actually need. An AI then spends tokens translating that prose back into code. It may regenerate code that already exists, has already been tested, and embodies decisions whose original rationale is only partly documented. Because the prose is incomplete and ambiguous, the new implementation can discard those decisions and reintroduce defects the existing code had already resolved.

That is why I believe spec-driven development is nonsense as a model for product development. The specification is not the product’s source of truth. It is one source of intent. Code is the executable reality. Tests show which claims about that reality currently hold. Context and history explain why it took this form.

We tried the same handoff idea decades ago. We called it the waterfall model, and it failed miserably because reality refused to follow the document. AI can produce the documents and code faster. It cannot make reality conform to the specification.

Waterfall has learned to generate code

The revival of spec-driven development is understandable. AI coding agents lack tacit context. Structured requirements, technical plans, task lists, and acceptance criteria help them work inside a codebase. They also make decisions easier to review.

But the sequence often preserves the old waterfall belief: product defines the truth, then engineering or an agent executes it.

Some modern workflows clarify requirements, generate plans, implement tasks, check results, and repeat until the output converges. That is better than a one-shot handoff. But repetition alone is not iteration. It is still waterfall if the specification remains the authority and code is repeatedly regenerated to conform to it.

Real iteration lets the specification, accumulated context, decision history, implementation discoveries, and current reality correct one another. The decisive question is not whether the spec changes. It is whether evidence from implementation and use can change the product intent.

If an API contradiction only creates another engineering task, the loop is cosmetic. If it makes the team reconsider the workflow, scope, or even the user promise, product discovery is actually happening.

Code is not merely output

I work as a Principal PM, but I also still develop software every day after more than 22 years of programming. From both sides of that boundary, the handoff model has never matched how products become real.

Code is where intent becomes executable behavior. It captures decisions that prose cannot express without becoming another programming language: data structures, control flow, failure handling, concurrency, integration contracts, and all the tradeoffs imposed by the existing system.

That does not make code the product strategy or make every implementation decision correct. It makes code the most precise expression of what the current system actually does, including the compromises and accumulated learning the specification does not contain.

Engineering is therefore not transcription. During implementation, developers are discovering the product with a different instrument.

So are AI coding agents. While implementing, they encounter constraints and contradictions the specification did not contain. But they can also lose context between runs, reinterpret ambiguous instructions, or change behavior whose purpose survives only in the code, tests, or decision history. Their output creates both evidence and new risk. Agentic development therefore needs more frequent reconciliation among intent, context, tests, and code, not a more exhaustive specification at the start.

Agents need structure, not exhaustive prescription

That is why AI agents need explicit guidance. Clear constraints reduce ambiguity. Acceptance criteria make outcomes testable. Architecture decisions prevent accidental drift. Tests preserve what has already been learned. Tools can expose contradictions cheaply and keep artifacts synchronized.

None of that requires pretending the specification is complete.

A useful specification defines the decision space. Exhaustive prescription claims to have already explored it. The first helps an agent act responsibly. The second encourages everyone to mistake document detail for product knowledge.

Keep intent and reality in parallel

A better model is not spec-driven. It keeps specification and code in parallel and iteratively updates both.

Start with four inputs:

• Specification: the intent, constraints, and evidence of success, without pretending to encode the entire implementation
• Context: the current product, users, organization, and technical system
• History: the decisions, tradeoffs, failures, and learning that produced the current state
• Current reality: what the code, integrations, data, and users reveal now

Then work from the codebase that already exists. Its application code, generated code, tests, architecture, libraries, and dependencies all contain reusable implementation and accumulated decisions. Developers guide the agent through that system and the smallest useful change. Tests, implementation discoveries, and user behavior update both the code and the specification.

The specification remains a living account of intent. The code remains the executable account of reality. Neither replaces the other, and neither should drift unchallenged.

This is faster because the agent changes an existing system instead of reconstructing it from prose. It is more stable because tested code, its tests, and the decisions encoded in both remain in place. It is less expensive because we do not keep spending tokens to regenerate an implementation that already works.

Reusable software is not only libraries, packages, frameworks, and open source. It is also the code already created in this project, whether written by people or generated by agents, together with the tests and history that explain how and why it works. The goal should not be to describe these assets again in our own ambiguous language so an agent can produce another version. The goal should be to preserve, combine, and adapt them in service of a clear intent.

What teams should do instead

Do not try to make prose complete enough to replace implementation. Use each artifact for what it does best.

• Use the specification to express intent: define the outcome, constraints, tradeoffs, and evidence of success.
• Start with the existing codebase: inspect application code, generated code, tests, dependencies, and decision history before creating anything new.
• Teach the agent this operating model: tell it that the specification expresses intent rather than the complete implementation. Require it to inspect what exists, explain what it will preserve or change, and surface contradictions instead of resolving them silently.
• Make the smallest testable change: preserve working behavior and reuse proven implementation unless replacing it is a deliberate decision.
• Let evidence change both artifacts: implementation findings, test results, and user behavior should update the code and the intent.

The measure of a good process is not how faithfully code follows a document. It is how quickly intent and executable reality can correct one another without discarding what the team has already learned.

This also brings product management and engineering closer. Once implementation evidence can change product intent, deciding what to build and building it become parts of the same loop rather than a handoff between separate roles. I explored that shift in We Will Not Need Product Managers and Engineers in the Same Way.

Before asking an agent to generate code, ask: what already exists, why does it work this way, and what is the smallest change that tests our intent?