I maintain seeing the identical thought in conversations about brokers: detailed specs are old-world overhead now. Give the mannequin a tough objective, let it discover, repair what comes again, transfer on. It sounds environment friendly but it surely additionally hides the price.
A easy immediate seems low cost and tempting as a result of it will get implementation began straight away. Then the correction loops begin. You overview output, make clear intent, ask for adjustments, rerun checks, discover the following hole, and do it once more. Somebody nonetheless has to determine whether or not the end result matches the actual objective. That particular person turns into the oracle.
On the different excessive, full formal specification is clearly costly up entrance. Writing acceptance standards, contract checks, or behavior-driven growth (BDD) situations takes actual effort. However the downstream value is completely different as a result of extra of the oracle is executable. A take a look at checks the identical situation each time. It doesn’t get drained, rushed, or optimistic 5 minutes earlier than lunch.
That’s the precise trade-off. The query just isn’t whether or not specification is nice or unhealthy. It’s the place the minimal whole value sits. For many agentic work, it’s someplace within the center: sufficient construction to constrain the work, sufficient examples to make intent concrete, and sufficient executable checks that overview doesn’t flip into guessing.
Zero spec just isn’t clever and lean; it’s simply pricey vibe-coding.
The bottleneck moved, not disappeared
Software program engineering was by no means primarily about typing and even producing code. It was about deciding what ought to exist, what ought to by no means occur, which trade-offs matter, and what “finished” means as soon as the issue touches the actual world.
For years, groups found lacking specification via human friction. A reviewer observed an edge case, QA discovered the trail no person described, a senior engineer carried half the actual necessities in his head and translated them one assembly at a time. None of that was elegant, but it surely did power ambiguity into the open.
Brokers change that essentially. They make implementation less expensive and far quicker. It additionally means an underspecified thought can flip right into a believable system earlier than anybody has actually agreed on what the system is meant to imply.
Within the outdated world, imprecise necessities bumped into human slowness. Within the agent world, imprecise necessities run into machine velocity.
That’s the reason specification all of the sudden feels essential once more. It was at all times essential. We simply used implementation value as a crude forcing operate and referred to as the end result course of.
Writing the spec just isn’t sufficient
That is the half I see individuals skip most frequently. They speak as if the sequence is straightforward: write the spec, then let the agent implement it. The lacking step is the costly one.
The spec itself wants overview.
Even a cautious spec can fail in acquainted methods. It will probably contradict itself or cowl the pleased path and say nothing helpful about retries, fee limits, or partial failure. It will probably describe conduct that sounds exact however can’t really be verified. And typically it’s exact in precisely the mistaken approach: it says what you wrote, not what you meant.
When an agent executes a flawed spec faithfully, the failure will get more durable to diagnose. The implementation might look coherent. It might even cross the checks you supplied. However the actual drawback lives upstream, within the spec, so fixing it means unwinding code and reasoning collectively.
That’s the reason I feel spec validation deserves its personal line merchandise. Earlier than implementation begins, somebody must ask a couple of plain questions. Is that this internally constant? Is it full sufficient for this process? Which elements are testable? The place are we nonetheless relying on human judgment? Which failure modes are lacking as a result of everybody silently assumed them?
Brokers will help right here, however provided that we use them for one thing extra helpful than “write necessities.” That immediate often produces polished fog. A greater immediate is rather more particular:
Draft the smallest spec that may let one other agent implement this safely. Embrace assumptions, non-goals, acceptance standards, edge circumstances, observable outcomes, and open questions. Mark which claims can develop into automated checks and which nonetheless require human overview.
After that, hand the draft to a special agent and inform it to assault the end result:
Discover contradictions, ambiguous phrases, hidden dependencies, untestable claims, lacking failure modes, and locations the place an implementation may cross the written standards whereas nonetheless violating the intent.
Even that straightforward workflow lowers the price of attending to a spec that’s price human judgment.
Why multi-agent methods want stronger contracts
A single agent engaged on a small, bounded process can usually get better from unfastened directions. The loop is tight, the blast radius is native, and a human can often steer it again on track when it drifts. People may even simply spot the drift to start with.
Multi-agent methods are a really completely different drawback. As soon as one agent’s output turns into one other agent’s enter, interpretive drift begins to compound. Agent B doesn’t know Agent A misunderstood a requirement by 10%. It simply treats the output as floor fact and retains going. By the point a human sees the end result, the unique mistake could also be buried beneath a number of layers of competent-looking work.
At that time, the spec is not simply steerage however extra like a contract.
That contract wants greater than a paragraph of intent. It wants schemas, invariants, allowed ambiguity, validation guidelines, and express failure conduct. In lots of circumstances, it additionally wants contract checks, typed interfaces, and machine-checkable handoff codecs. The handoff is a part of the product, which is much less glamorous than individuals hoped, however a lot nearer to actuality.
That is additionally the place BDD and executable acceptance checks belong. Their worth isn’t just the methodology, it’s that they transfer a part of the human oracle into one thing repeatable. When conduct is steady sufficient to specify exactly, an executable spec is usually cheaper than one other spherical of overview.
A spec ought to have an expiration date
There’s one other failure that groups make right here: It exhibits up once they maintain pushing on the specification curve as if extra textual content is at all times safer. It’s not. A minimum of for present fashions it’s not.
Chroma’s work on context rot makes the primary a part of the issue clear: Mannequin efficiency will get much less dependable because the enter grows, even on easy duties. In coding initiatives there’s a second drawback on high of that. The extra design prose, examples, plans, feedback, tickets, and outdated acceptance standards you stuff into the context, the much less apparent it turns into which elements are directions and which elements are artifacts.
I might not name this immediate injection within the safety sense. No person is attempting to assault the mannequin. It’s nearer to self-inflicted instruction drift. The context incorporates outdated design intent, present implementation, half-valid examples, generated plans from three periods in the past, and possibly a stale software program design doc that also describes lessons that not exist. At that time, the mannequin just isn’t studying one spec, it’s averaging throughout competing sources of fact.
That’s when over-specification stops serving to and begins complicated the mannequin. The agent can not inform whether or not a paragraph is an lively requirement, a historic notice, or one thing the code has already changed.
A design doc is helpful early as a result of the code doesn’t exist but. Later, it must shrink. As soon as interfaces, checks, and invariants are actual, the detailed construct plan ought to begin disappearing. “Hold the elements” code is unhealthy at expressing by itself: enterprise rationale, non-goals, security constraints, exterior contracts, and the few invariants you don’t want rediscovered by trial and error. Delete the prose that simply restates what lessons and strategies already do.
In any other case, you find yourself with two specs. People will complain about that in overview. Brokers will usually attempt to obey each.
APIs could make code behave like spec
There’s additionally a extra optimistic model of this story. Some codebases attain the “code is the spec” level quicker than others, and API design is a giant purpose why.
If an inside API hides conduct behind conventions, weakly typed parameters, setup magic, and generic errors, an agent can’t deal with the code because the spec. It has to reconstruct the principles from scattered prose and trial and error. That’s gradual for people and worse for fashions.
The alternative can be true. An API with express names, task-level strategies, sturdy varieties, readable validation, helpful examples, and actionable errors offers the agent one thing concrete to face on. If the agent can examine the floor space, see what a way does, perceive what enter is authorized, and get better from errors with out guessing, then the code carries rather more of the specification load by itself.
That is the place the AI-friendly API design concepts matter in apply. Express discoverability beats conference. Strategies ought to line up with actual duties as a substitute of forcing the agent via a dozen fragile steps. Varieties and validation ought to present what authorized enter seems like. Error messages ought to level to the following repair, not simply announce failure. Introspection and examples assist the mannequin be taught the form of the API from the codebase it already has. Efficiency transparency issues too, as a result of an agent will fortunately write an accurate and horrible loop round an costly name if the API offers it no clue.
This isn’t solely about public SDKs. It applies to inside service boundaries, library purchasers, repository abstractions, and even the helper lessons in a big monorepo. The better an API is to find and examine, the simpler it’s for an agent to deal with the code because the authoritative spec as a substitute of dragging extra prose into the context. I have written about all this before in more depth if you are interested.
The place to take a position
What I strongly consider is that there is no such thing as a single correct amount of specification. The reply will depend on the sort of work you’re doing. For a small, well-bounded process, the candy spot is often structured intent: the objective, a couple of examples, non-goals, and clear acceptance standards. That’s usually sufficient to maintain the agent productive with out making setup heavier than the duty.
For deterministic work comparable to CRUD flows, API integrations, and information transformations, the optimum strikes to the appropriate. These domains are straightforward to constrain and simple to check. Extra specification pays for itself shortly as a result of it cuts repeated overview and rework. That is the place BDD, contract checks, and executable acceptance standards assist most.
For exploratory work comparable to structure choices, analysis synthesis, or novel product concepts, the optimum strikes left once more. Over-specification can kill the very flexibility that makes the agent helpful. In that case, I might fairly specify boundaries than outcomes: what should be true, what should not occur, what proof is required, and which selections nonetheless want a human.
For multi-agent pipelines, the optimum strikes proper as soon as extra. Each boundary between brokers wants a contract. With out that, you aren’t coordinating a system. You’re stacking interpretations and hoping they cancel out.
The widespread rule throughout all 4 circumstances is straightforward: validate the spec earlier than you scale the implementation.
What survives from Agile and XP
I don’t assume brokers make Agile or XP irrelevant. They make the helpful elements simpler to separate from the elements individuals had been already tolerating.
The primary casualty is the ceremony that existed principally to coordinate human effort hour by hour. Day by day standing conferences, inflated backlog rituals, and estimates offered with extra confidence than data don’t get stronger as a result of an agent wrote the code. If something, they get weaker. Brokers can change the form of a process so shortly that outdated effort estimates develop into fiction even quicker than earlier than. That doesn’t imply planning disappears. It means planning has to cease pretending it might predict implementation value with the identical consolation it had when code was the gradual half.
What survives from Agile is the suggestions logic. Quick cycles nonetheless matter. Skinny vertical slices nonetheless matter. Buyer or stakeholder overview nonetheless issues. Working software program remains to be higher than progress theater as a result of brokers can generate plenty of convincing wrongness in a short time. The truth is, I might argue that quick suggestions issues extra now, not much less. If a crew can go from imprecise thought to giant implementation in a morning, it additionally wants a method to uncover by lunchtime that the thought was mistaken.
XP survives even higher as a result of it was at all times about maintaining studying near the code. Take a look at-first pondering nonetheless issues as a result of executable checks get extra beneficial as implementation will get cheaper. Steady integration nonetheless issues as a result of each agent change wants a gate. Refactoring nonetheless issues as a result of brokers can fortunately produce code that works, passes a couple of checks, and nonetheless leaves you with a construction no person desires to take care of subsequent month. The machine has no satisfaction right here. It would generate a large number with good confidence.
Pair programming adjustments form, however the core thought survives. I nonetheless need design judgment near code era. Generally that appears like a human working instantly with one coding agent. Generally it seems like one mannequin producing code whereas one other mannequin opinions it with a narrower transient. Both approach, the helpful a part of pairing was by no means two keyboards in concord subsequent to one another over a espresso with their people. It was quick design suggestions earlier than the code settled into place.
Small releases additionally survive, possibly for a much less romantic purpose. When brokers could make very giant adjustments cheaply, the temptation is to simply accept very giant diffs cheaply too. That could be a unhealthy thought. Evaluate, rollback, and prognosis are simpler finished in small batches. A brief-lived characteristic department is simpler to purpose about than a 4,000-line monster.
What fades is methodology as reassurance. What survives is methodology as error detection. Agile and XP had been at their greatest once they made it cheaper to find that the crew understood the issue badly. That’s nonetheless the job. The agent period simply removes a couple of excuses and provides new methods to be mistaken at excessive velocity.
The actual leverage
The promise of agentic growth is actual. Brokers could make implementation dramatically cheaper, however as soon as code will get low cost, specification and verification develop into the place the place initiatives succeed or fail.
The groups that get essentially the most leverage is not going to be the groups that specify the least. They would be the groups that know when three bullets are sufficient, once they want an actual contract, and when the contract has to develop into executable.
The brokers are getting higher. The choices are nonetheless ours.