The Spec Is Not the Method
Agents need context to do useful work. Large upfront specifications are one way to provide that context. The case currently being made in software-intensive industries, with increasing volume and under the emerging label of spec-driven development (SDD), is that this is how software development in the agent era should be done: write the specification carefully, let the agents implement it at speed, and the productivity gain takes care of the rest.
What SDD is actually describing is a workaround. The practice is shaped, at every point, by what the technology cannot yet do for itself. Treating that workaround as the methodology, rather than as the response to a present-day limitation, is a category error with consequences. The two descriptions point at different futures, and committing to the wrong one has costs the advocates’ own framing makes difficult to see.
What the practice is actually responding to
The need for context is real, and it is the part of the advocates’ argument that is most clearly correct. An agent asked to make a change to a codebase without an understanding of the architecture it sits in, the constraints it has to honour, the conventions the team has settled on, and the history that produced the current shape of things will produce work that is locally plausible and systemically wrong. Nobody serious disputes this.
What is open is the question of how that context should be provided. The current dominant answer, large upfront specifications, is one solution. It emerged first partly because it is the one most easily executed with the tooling that exists today and partly because it maps onto practices the industry already recognises. But the specific form of the practice (large, comprehensive, written in advance) tracks the specific shape of what agents currently cannot do for themselves. They cannot read a codebase the way a senior engineer reads it. They cannot ask the right people the right questions. They cannot accumulate tacit understanding through sustained contact with a system. The missing capability gets supplied externally, in the form of a document.
That is the signature of a workaround. As the technology develops other ways of acquiring context (better retrieval over codebases, access to architectural documents and team conventions, memory across sessions, the ability to ask), the case for routing everything through a large upfront specification erodes. Not all at once, and not uniformly, but in a direction that is fairly easy to anticipate. The practice is built on a constraint the industry is actively working to remove.
The pattern is recognisable because the field has just produced a smaller version of it. In 2023, prompt engineering was the term the industry had settled on for the skill of working productively with large language models. A new discipline had appeared, the argument ran, and the people who developed fluency in it would occupy a meaningful role in how the technology was used. The early advocates were not wrong about what they were noticing: writing better prompts did produce better results, and the skill was real. What they were wrong about was the scale of the claim. As the models matured, the gap that had made the skill load-bearing narrowed. Two years on, the standalone role had largely receded; the skill persists, absorbed into broader engineering work. The mechanism is the same one operating now. A current limitation produces a practice that compensates for it. The practice is genuine. The error sits in the inference from “this works now” to “this is what the field has become.” SDD is making that inference at a larger scale than prompt engineering did, with more invested, and the underlying pattern is no different.
The mechanism has not changed
There is a piece of evidence the current advocacy quietly works around, and it is not a small one. The field has run this experiment before. For roughly three decades, from the late 1960s through the early 2000s, large upfront specifications were the dominant approach to building non-trivial software. The results were repeatedly and expensively bad. Projects came in late, came in wrong, came in not at all. The pattern was visible enough, and the cost was high enough, that the response to it (the development of iterative and incremental approaches under various names, eventually consolidated under the Agile banner) became the most significant methodological shift the field has seen.
What made large specs fail was structural. A specification is written against an understanding of the problem that necessarily precedes contact with the implementation of it, and contact with implementation produces information that the specification could not have contained. The unknown unknowns of the original framing become visible only through the work. The unknowable unknowns remain unknowable regardless, and the specification’s commitment to having captured them becomes a liability rather than an asset. This is the epistemic gap, and it is the mechanism that made the pre-agile experience as costly as it was.
The question worth putting to the current advocacy is precise: which part of this mechanism do you think has changed?
The unknowns are still unknown. The unknowables are still unknowable. A specification written today, however carefully, still cannot contain information that does not yet exist at the point of writing. Agents do not alter this. They speed up the act of implementation, which is a real and useful change, but they do not give the specification’s author retroactive access to information that the implementation has not yet surfaced. The thing that made large specs fail in 1995 is the thing that will make them fail in 2026, on the same evidence, for the same reasons.
The current advocacy rarely makes this argument directly, because the honest version of it is hard to defend. What SDD does instead is shift the subject. The discussion becomes about engineering velocity, about the cost of agent capacity, about the productivity implications of the new tooling. These are interesting topics. They are not the topic on which the historical evidence was produced, and they do not, on examination, alter what that evidence said.
What the cost actually looks like
There is an implicit economic argument inside SDD that deserves to be examined on its own terms. The argument runs, roughly, that agents have made engineering capacity cheap, so the cost of producing a wrong implementation has dropped, so larger specifications become defensible because the cost of being wrong has dropped with them. Each part of this argument is worth checking.
The first part concerns production cost. A wrong specification, executed by agents, wastes both tokens and engineering hours. The token cost is a new cost layer that did not exist in the human-only era, and it is borne by the organisation regardless of whether the regenerated version is better than what it replaced. The engineering-hours cost has not dropped in the way the advocacy assumes. Engineers are still required to evaluate what the agents have produced, to integrate it with the surrounding system, to handle the work the agents could not. The productivity gain that the advocacy treats as established is a forecast rather than a measurement. It may materialise, at a smaller scale than currently assumed. The economics of producing the wrong implementation have probably gotten worse rather than better.
Get Bruno Baketarić’s stories in your inbox
Join Medium for free to get updates from this writer.
The second part concerns the cost of being wrong in the market. A release that does not solve the problem it claimed to solve damages the relationship with the people who depended on it. This is exactly the cost the field paid throughout the pre-agile decades, and it is not a cost agents alter. If anything, the speed at which agents enable releases to be produced lowers the friction that previously slowed bad releases down, which suggests the market-credibility cost has become more acute rather than less. The advocacy focuses on the engineering-team frame, where the productivity story is most compelling, and neglects the market frame, where the historical evidence was most damning. The neglect is not accidental, but it is consequential.
Iterative and incremental approaches do not escape this cost; they distribute it differently. A team that releases something incomplete, names it as incomplete, and invites the customer into the process of refining it is making a different kind of claim on the market’s patience. The cost of being wrong is spread across smaller commitments, each of which can be revised before the damage compounds. The market relationship becomes one of collaborative refinement rather than promised delivery, and this is part of what makes the iterative stance work where it works. It is also part of what makes the iterative stance unavailable in some contexts, a point that has its own analysis below.
The third part concerns capacity. Engineering capacity is being cut in many organisations on the basis of the productivity-gain forecast, before that forecast has been validated. The pain signal that historically forced organisations to confront the cost of bad specs is being muted at the moment when the actual cost of being wrong is potentially rising. The pattern is familiar from elsewhere in this series. Pressure from markets and boards to demonstrate AI capability gets converted, through several links of the organisational chain, into headcount decisions on the basis of claims that have not been tested. The capacity that would have absorbed the cost of bad specifications is being removed in advance of the evidence that it is no longer needed. The human evaluation bottleneck is not changing in the meantime, because evaluation does not get faster the way generation does. The total cost of being wrong has likely gone up, distributed across phases that are harder to see and harder to recover from than the implementation phase used to be.
The same move, one level down
Not every market or customer can be drawn into the iterative journey directly. Some are paying for a finished thing and will not engage with the process by which it became finished. Some operate in regulatory environments that require commitments the iterative posture structurally cannot make. Agile thinking developed a response to this: roles that sit at the interface between the market and the engineering team. Product Owners, Product Managers, UX practitioners, depending on the context, acting as proxies for stakeholders who cannot be in the room, or as translators and coordinators where those stakeholders are present but the conversation needs help. The arrangement is partial. It does not pretend to solve the underlying constraint, only to mitigate it.
One of the claims now circulating around SDD is that these roles can feed requirements and specifications directly into agents, dispensing with the engineering-team intermediation the arrangement traditionally relied on. The promise is faster delivery and reduced cost: the technical-translation work that the engineering team used to do gets absorbed by the agent, and the role-holder operates directly with the tool.
The error is the same one the essay has been describing, at a smaller scale. The role exists because some work cannot be done without it: holding the market’s intent steady where the market is absent, translating between two kinds of understanding where it is present, making calls at the interface when judgement is needed. None of this is implementation-speed work, which is what the agent provides. The role-holder asked to feed an agent directly is being asked to do the same work as before, with less technical depth available than the engineering arrangement provided, and with less ability to evaluate what the agent produces. The agent fills a gap the role never filled. The role’s actual work is unchanged in volume and harder in form.
This works where the technical-depth requirement is shallow, which describes the demonstration cases that get cited around the claim: simple applications, basic CRUD, the kinds of systems where the gap between market intent and technical implementation is small enough that a non-technical role-holder can bridge it alone. It fails as soon as the technical-depth requirement becomes the bottleneck, which is where non-trivial software development actually sits.
A note on honesty. The role itself has well-known structural weaknesses. Organisations frequently install it and then refuse to give it the authority its function requires. The Product Owner without the standing to make calls, the Product Manager whose decisions are routinely overruled by stakeholders who declined to be in the conversation: these are real and common failures of how the role is supported. They are not, however, what direct-to-agent fixes. The structural problem is that the surrounding system does not equip the role; the SDD proposal does not equip it differently, it removes it on the assumption that the agent will do its work. The original problem is inherited rather than solved, with one less person in the chain who might have noticed it.
The pattern, in other words, is not specific to the methodology level. It operates wherever a current limitation gets compensated for by a practice that is then mistaken for a replacement for the role or function the limitation prevented.
A new balance, not yet settled
What agents introduce is a new variable in an equation that already had several. The equation has multiple dimensions, and they pull in different directions. The cost of being wrong about a specification. The cost of engineering capacity sitting idle while specifications are refined. The token economics of regeneration. The cognitive load on the humans who evaluate what the agents have produced. The learning value of contact with implementation. Some of these favour larger commitments; others favour smaller ones. None of them is dominant in a way that settles the question on its own.
A new balance needs to emerge across these dimensions, in the present tense, through a process that is genuinely underway and not yet settled. The advocates of large upfront specs have committed to a position that optimises one dimension, engineering velocity, on the assumption that the production cost has dropped enough to make larger commitments rational. The reflexive defenders of iterative-at-all-costs have committed to a position that optimises a different dimension, learning amplification, on the assumption that the conditions for iteration to deliver remain unchanged. Neither of these is the answer the situation has actually produced. The situation has produced a question, and the question is what balance, across all the dimensions, fits the new variable that has been introduced.
There is an internal tension in the current advocacy worth naming. If the advocates believe that agents will continue to improve, including in their ability to acquire context for themselves, then the case for large upfront specifications erodes as that capability develops. The specification is the workaround for a constraint that will lift. If, conversely, they do not believe agents will improve in that direction, then they should not believe the productivity story that is driving the capacity reductions either, because that story depends on similar improvements in adjacent capabilities. The two positions do not sit comfortably together, and the advocacy generally avoids holding them at the same time, because holding them together makes the incoherence visible.
The balance that does emerge is unlikely to look like large specs upfront, for a reason that is more structural than methodological. The constraint that makes large specs attractive at the present moment, the inability of agents to acquire context for themselves, is the constraint the industry is actively working to remove. The investments being made in retrieval, in memory, in agent-to-codebase interfaces, in tool-access and agent-to-agent protocols that let networks of specialised agents form (some of them dedicated to context-provision), in the various means by which an agent might come to understand a system without being told everything in advance, are investments in eliminating the gap that the specification fills. As the gap closes, the practice loses its rationale. What replaces it is not yet visible, but it will almost certainly involve agents acquiring context through means other than reading a document that a human wrote in advance.
What the question actually is
The more interesting question, once the diagnostic is accepted, is what shorter, iterative, incremental interactions deliver when one of the participants is an agent rather than a human. The forms of that interaction, the structures that support it, the way the learning loop functions when one side of the loop is operating at a different cognitive tempo from the other, the relationship between human evaluation capacity and agent generation capacity, the question of where the meaningful units of commitment sit when the cost of the act of generation has shifted: these are open questions, and they are the ones worth working on.
The preconditions for that work to deliver are not different from the preconditions any iterative practice depends on, examined in earlier essays in this series. They are the conditions the surrounding organisational system most reliably fails to provide. That is a real constraint, and it is not one this essay is going to resolve. What this essay has done is name the current moment for what it is. SDD is not describing the future of the field. It is describing a present-day workaround that is unlikely to outlive the constraint that produced it. The question that comes after, the question of what does outlive that constraint, is the more interesting one. It is the one worth asking.
