I hold seeing the identical concept in conversations about brokers: Detailed specs are old-world overhead now. Give the mannequin a tough purpose, let it discover, repair what comes again, transfer on. It sounds environment friendly but it surely additionally hides the fee.
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 assessment output, make clear intent, ask for modifications, rerun assessments, discover the subsequent hole, and do it once more. Somebody nonetheless has to determine whether or not the outcome matches the true purpose. That particular person turns into the oracle.
On the different excessive, full formal specification is clearly costly up entrance. Writing acceptance standards, contract assessments, or behavior-driven improvement (BDD) situations takes actual effort. However the downstream value is totally 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 isn’t whether or not specification is sweet 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 assessment doesn’t flip into guessing.
Zero spec 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 true world.
For years, groups found lacking specification by way of human friction. A reviewer seen an edge case, QA discovered the trail no person described, a senior engineer carried half the true necessities in his head and translated them one assembly at a time. None of that was elegant, but it surely did drive ambiguity into the open.
Brokers change that basically. They make implementation less expensive and far quicker. It additionally means an underspecified concept can flip right into a believable system earlier than anybody has actually agreed on what the system is meant to imply.
Within the previous world, obscure necessities bumped into human slowness. Within the agent world, obscure necessities run into machine velocity.
That’s why specification instantly feels necessary once more. It was at all times necessary. We simply used implementation value as a crude forcing perform and known as the outcome course of.
Writing the spec 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 assessment.
Even a cautious spec can fail in acquainted methods. It may well contradict itself or cowl the pleased path and say nothing helpful about retries, fee limits, or partial failure. It may well describe conduct that sounds exact however can’t really be verified. And generally it’s exact in precisely the flawed means: 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 could even cross the checks you supplied. However the true drawback lives upstream, within the spec, so fixing it means unwinding code and reasoning collectively.
That’s why I feel spec validation deserves its personal line merchandise. Earlier than implementation begins, somebody must ask a number 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 may 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 way more particular:
Draft the smallest spec that will let one other agent implement this safely. Embody assumptions, nongoals, acceptance standards, edge instances, observable outcomes, and open questions. Mark which claims can change into automated assessments and which nonetheless require human assessment.
After that, hand the draft to a unique agent and inform it to assault the outcome:
Discover contradictions, ambiguous phrases, hidden dependencies, untestable claims, lacking failure modes, and locations the place an implementation might 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 techniques want stronger contracts
A single agent engaged on a small, bounded process can typically recuperate from unfastened directions. The loop is tight, the blast radius is native, and a human can often steer it again on the right track when it drifts. People may even simply spot the drift to start with.
Multi-agent techniques are a really totally 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 reality and retains going. By the point a human sees the outcome, the unique mistake could also be buried beneath a number of layers of competent-looking work.
At that time, the spec is not simply steering however extra like a contract.
That contract wants greater than a paragraph of intent. It wants schemas, invariants, allowed ambiguity, validation guidelines, and specific failure conduct. In lots of instances, it additionally wants contract assessments, 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 assessments belong. Their worth is not only 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 commonly cheaper than one other spherical of assessment.
A spec ought to have an expiration date
There may be one other failure that groups make right here: It exhibits up after they hold pushing on the specification curve as if extra textual content is at all times safer. It’s not. No less than 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 tasks there’s a second drawback on prime of that. The extra design prose, examples, plans, feedback, tickets, and previous acceptance standards you stuff into the context, the much less apparent it turns into which elements are directions and which elements are artifacts.
I wouldn’t name this immediate injection within the safety sense. No person is making an attempt to assault the mannequin. It’s nearer to self-inflicted instruction drift. The context comprises previous 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 isn’t studying one spec, it’s averaging throughout competing sources of reality.
That’s when overspecification stops serving to and begins complicated the mannequin. The agent can not inform whether or not a paragraph is an lively requirement, a historic observe, 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, assessments, 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 do not need 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 assessment. Brokers will typically attempt to obey each.
APIs could make code behave like spec
There may be 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 cause why.
If an inner 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 other can be true. An API with specific names, task-level strategies, sturdy sorts, readable validation, helpful examples, and actionable errors provides the agent one thing concrete to face on. If the agent can examine the floor space, see what a technique does, perceive what enter is authorized, and recuperate from errors with out guessing, then the code carries way more of the specification load by itself.
That is the place the AI-friendly API design concepts matter in observe. Express discoverability beats conference. Strategies ought to line up with actual duties as an alternative of forcing the agent by way of a dozen fragile steps. Varieties and validation ought to present what authorized enter seems like. Error messages ought to level to the subsequent repair, not simply announce failure. Introspection and examples assist the mannequin study 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 provides it no clue.
This isn’t solely about public SDKs. It applies to inner service boundaries, library purchasers, repository abstractions, and even the helper lessons in a big monorepo. The simpler an API is to find and examine, the better it’s for an agent to deal with the code because the authoritative spec as an alternative of dragging extra prose into the context. I’ve written about all this earlier than in additional depth in the event you’re .
The place to take a position
What I strongly imagine is that there isn’t a single correct quantity of specification. The reply is dependent upon the type of work you’re doing. For a small, well-bounded process, the candy spot is often structured intent: the purpose, a number of examples, nongoals, and clear acceptance standards. That’s typically sufficient to maintain the agent productive with out making setup heavier than the duty.
For deterministic work akin to CRUD flows, API integrations, and information transformations, the optimum strikes to the best. These domains are straightforward to constrain and simple to check. Extra specification pays for itself rapidly as a result of it cuts repeated assessment and rework. That is the place BDD, contract assessments, and executable acceptance standards assist most.
For exploratory work akin 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 slightly 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 frequent rule throughout all 4 instances is straightforward: Validate the spec earlier than you scale the implementation.
What survives from Agile and XP
I don’t suppose brokers make Agile or XP irrelevant. They make the helpful elements simpler to separate from the elements individuals have been already tolerating.
The primary casualty is the ceremony that existed principally to coordinate human effort hour by hour. Each 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 rapidly that previous effort estimates change into fiction even quicker than earlier than. That doesn’t imply planning disappears. It means planning has to cease pretending it may well predict implementation value with the identical consolation it had when code was the gradual half.
What survives from Agile is the suggestions logic. Brief cycles nonetheless matter. Skinny vertical slices nonetheless matter. Buyer or stakeholder assessment nonetheless issues. Working software program continues to be higher than progress theater as a result of brokers can generate plenty of convincing wrongness in a short time. Actually, I might argue that quick suggestions issues extra now, not much less. If a crew can go from obscure concept to massive implementation in a morning, it additionally wants a option to uncover by lunchtime that the concept was flawed.
XP survives even higher as a result of it was at all times about conserving studying near the code. Take a look at-first considering nonetheless issues as a result of executable checks get extra precious 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 number of assessments, and nonetheless leaves you with a construction no person desires to take care of subsequent month. The machine has no satisfaction right here. It is going to generate a multitude with good confidence.
Pair programming modifications form, however the core concept survives. I nonetheless need design judgment near code era. Generally that appears like a human working immediately with one coding agent. Generally it seems like one mannequin producing code whereas one other mannequin critiques it with a narrower transient. Both means, 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 cause. When brokers could make very massive modifications cheaply, the temptation is to just accept very massive diffs cheaply too. That could be a unhealthy concept. Overview, rollback, and prognosis are simpler finished in small batches. A brief-lived function department is less complicated to cause about than a 4,000-line monster.
What fades is methodology as reassurance. What survives is methodology as error detection. Agile and XP have been at their finest after they made it cheaper to find that the crew understood the issue badly. That’s nonetheless the job. The agent period simply removes a number of excuses and provides new methods to be flawed at excessive velocity.
The true leverage
The promise of agentic improvement is actual. Brokers could make implementation dramatically cheaper, however as soon as code will get low-cost, specification and verification change into the place the place tasks succeed or fail.
The groups that get probably the most leverage is not going to be the groups that specify the least. They’ll be the groups that know when three bullets are sufficient, after they want an actual contract, and when the contract has to change into executable.
The brokers are getting higher. The choices are nonetheless ours.
