I preserve seeing the identical thought in conversations about brokers: Detailed specs are old-world overhead now. Give the mannequin a tough aim, let it discover, repair what comes again, transfer on. It sounds environment friendly but it surely additionally hides the price.
A easy immediate seems to be low-cost and tempting as a result of it will get implementation began immediately. Then the correction loops begin. You evaluate output, make clear intent, ask for adjustments, rerun assessments, discover the subsequent hole, and do it once more. Somebody nonetheless has to resolve whether or not the consequence matches the actual aim. That individual 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) eventualities takes actual effort. However the downstream price 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 is just not whether or not specification is nice or dangerous. It’s the place the minimal whole price 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 evaluate doesn’t flip into guessing.
Zero spec is just not clever and lean; it’s simply expensive 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 “achieved” 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 one 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 drive ambiguity into the open.
Brokers change that basically. They make implementation less expensive and far sooner. 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 previous world, imprecise necessities bumped into human slowness. Within the agent world, imprecise necessities run into machine pace.
That’s why specification all of a sudden feels essential once more. It was at all times essential. We simply used implementation price as a crude forcing operate and referred to as the consequence course of.
Writing the spec is just not sufficient
That is the half I see individuals skip most frequently. They discuss as if the sequence is easy: write the spec, then let the agent implement it. The lacking step is the costly one.
The spec itself wants evaluate.
Even a cautious spec can fail in acquainted methods. It could possibly contradict itself or cowl the glad path and say nothing helpful about retries, fee limits, or partial failure. It could possibly describe habits that sounds exact however can not really be verified. And generally it’s exact in precisely the improper manner: it says what you wrote, not what you meant.
When an agent executes a flawed spec faithfully, the failure will get tougher to diagnose. The implementation could look coherent. It might even move the checks you supplied. However the actual downside lives upstream, within the spec, so fixing it means unwinding code and reasoning collectively.
That’s why I believe 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 activity? Which components 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 might 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 far more particular:
Draft the smallest spec that will let one other agent implement this safely. Embody assumptions, nongoals, acceptance standards, edge circumstances, observable outcomes, and open questions. Mark which claims can change into automated assessments and which nonetheless require human evaluate.
After that, hand the draft to a special agent and inform it to assault the consequence:
Discover contradictions, ambiguous phrases, hidden dependencies, untestable claims, lacking failure modes, and locations the place an implementation may move the written standards whereas nonetheless violating the intent.
Even that easy 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 activity can usually get better from free directions. The loop is tight, the blast radius is native, and a human can often steer it again on target when it drifts. People may even simply spot the drift to start with.
Multi-agent techniques are a really completely different downside. 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 consequence, the unique mistake could also be buried underneath a number of layers of competent-looking work.
At that time, the spec is now 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 express failure habits. In lots of circumstances, 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 isn’t just the methodology, it’s that they transfer a part of the human oracle into one thing repeatable. When habits is secure sufficient to specify exactly, an executable spec is usually cheaper than one other spherical of evaluate.
A spec ought to have an expiration date
There may be one other failure that groups make right here: It reveals up once they preserve pushing on the specification curve as if extra textual content is at all times safer. It’s not. Not 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 initiatives there’s a second downside on high 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 components are directions and which components are artifacts.
I wouldn’t name this immediate injection within the safety sense. No one is attempting to assault the mannequin. It’s nearer to self-inflicted instruction drift. The context accommodates previous design intent, present implementation, half-valid examples, generated plans from three classes in the past, and perhaps a stale software program design doc that also describes courses that now not exist. At that time, the mannequin is just not studying one spec, it’s averaging throughout competing sources of fact.
That’s when overspecification stops serving to and begins complicated the mannequin. The agent can now not inform whether or not a paragraph is an lively requirement, a historic be aware, or one thing the code has already changed.
A design doc is beneficial 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 components” code is dangerous 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 courses and strategies already do.
In any other case, you find yourself with two specs. People will complain about that in evaluate. Brokers will usually 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 sooner than others, and API design is an enormous purpose why.
If an inner API hides habits behind conventions, weakly typed parameters, setup magic, and generic errors, an agent can not 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 express names, task-level strategies, sturdy varieties, 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 get better from errors with out guessing, then the code carries far 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 a substitute of forcing the agent via a dozen fragile steps. Varieties and validation ought to present what authorized enter seems to be 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 courses 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 a substitute of dragging extra prose into the context. I’ve written about all this earlier than in additional depth for those who’re .
The place to speculate
What I strongly consider is that there isn’t any single correct amount of specification. The reply relies on the type of work you’re doing. For a small, well-bounded activity, the candy spot is often structured intent: the aim, a number of examples, nongoals, and clear acceptance standards. That’s usually sufficient to maintain the agent productive with out making setup heavier than the duty.
For deterministic work similar to CRUD flows, API integrations, and information transformations, the optimum strikes to the proper. These domains are straightforward to constrain and simple to check. Extra specification pays for itself shortly as a result of it cuts repeated evaluate and rework. That is the place BDD, contract assessments, and executable acceptance standards assist most.
For exploratory work similar 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 moderately specify boundaries than outcomes: what should be true, what should not occur, what proof is required, and which choices 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 easy: 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 components simpler to separate from the components individuals have been already tolerating.
The primary casualty is the ceremony that existed largely to coordinate human effort hour by hour. Each day standing conferences, inflated backlog rituals, and estimates introduced with extra confidence than info 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 activity so shortly that previous effort estimates change into fiction even sooner than earlier than. That doesn’t imply planning disappears. It means planning has to cease pretending it might probably predict implementation price 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 evaluate nonetheless issues. Working software program remains to be higher than progress theater as a result of brokers can generate quite a lot of convincing wrongness in a short time. The truth is, I might argue that quick suggestions issues extra now, not much less. If a workforce can go from imprecise thought to massive implementation in a morning, it additionally wants a approach to uncover by lunchtime that the concept was improper.
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 useful 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 one desires to keep up subsequent month. The machine has no pleasure right here. It’s going to generate a large number with good confidence.
Pair programming adjustments form, however the core thought survives. I nonetheless need design judgment near code era. Typically that appears like a human working immediately with one coding agent. Typically it seems to be like one mannequin producing code whereas one other mannequin evaluations it with a narrower transient. Both manner, 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, perhaps for a much less romantic purpose. When brokers could make very massive adjustments cheaply, the temptation is to just accept very massive diffs cheaply too. That could be a dangerous thought. Evaluation, rollback, and prognosis are simpler achieved 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 have been at their greatest once they made it cheaper to find that the workforce understood the issue badly. That’s nonetheless the job. The agent period simply removes a number of excuses and provides new methods to be improper at excessive pace.
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 initiatives succeed or fail.
The groups that get essentially the most leverage won’t be the groups that specify the least. They’ll be the groups that know when three bullets are sufficient, once they want an actual contract, and when the contract has to change into executable.
The brokers are getting higher. The choices are nonetheless ours.
