I maintain seeing the identical concept 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 nevertheless it additionally hides the associated fee.
A easy immediate appears low cost and tempting as a result of it will get implementation began straight away. Then the correction loops begin. You evaluate output, make clear intent, ask for modifications, rerun exams, discover the subsequent hole, and do it once more. Somebody nonetheless has to determine whether or not the outcome matches the true objective. That individual turns into the oracle.
On the different excessive, full formal specification is clearly costly up entrance. Writing acceptance standards, contract exams, or behavior-driven improvement (BDD) eventualities takes actual effort. However the downstream value is completely different as a result of extra of the oracle is executable. A check 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 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 evaluate doesn’t flip into guessing.
Zero spec just isn’t 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 “completed” means as soon as the issue touches the true world.
For years, groups found lacking specification by 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, nevertheless it did power ambiguity into the open.
Brokers change that essentially. 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 outdated world, imprecise necessities bumped into human slowness. Within the agent world, imprecise necessities run into machine velocity.
That’s why specification all of the sudden feels vital once more. It was all the time vital. We simply used implementation value as a crude forcing perform and known as the outcome course of.
Writing the spec just isn’t sufficient
That is the half I see individuals skip most frequently. They discuss 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 evaluate.
Even a cautious spec can fail in acquainted methods. It will probably contradict itself or cowl the comfortable path and say nothing helpful about retries, charge limits, or partial failure. It will probably describe habits that sounds exact however can’t really be verified. And generally it’s exact in precisely the fallacious 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 could even go the checks you offered. However the true drawback 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 couple of plain questions. Is that this internally constant? Is it full sufficient for this process? 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 may also help right here, however provided that we use them for one thing extra helpful than “write necessities.” That immediate normally produces polished fog. A greater immediate is far more particular:
Draft the smallest spec that might let one other agent implement this safely. Embrace assumptions, nongoals, acceptance standards, edge instances, observable outcomes, and open questions. Mark which claims can develop into automated exams and which nonetheless require human evaluate.
After that, hand the draft to a special 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 may go the written standards whereas nonetheless violating the intent.
Even that easy workflow lowers the price of attending to a spec that’s value human judgment.
Why multi-agent techniques 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 normally steer it again on track when it drifts. People may even simply spot the drift to start with.
Multi-agent techniques 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 outcome, 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 specific failure habits. In lots of instances, it additionally wants contract exams, 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 exams belong. Their worth is not only 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 after they maintain pushing on the specification curve as if extra textual content is all the time 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 components are directions and which components 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 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 now not exist. At that time, the mannequin just isn’t 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 energetic requirement, a historic notice, 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, exams, and invariants are actual, the detailed construct plan ought to begin disappearing. “Hold the components” 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 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 quicker than others, and API design is a giant purpose why.
If an inside API hides habits 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 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 far more of the specification load by itself.
That is the place the AI-friendly API design concepts matter in follow. Specific discoverability beats conference. Strategies ought to line up with actual duties as a substitute of forcing the agent by a dozen fragile steps. Varieties and validation ought to present what authorized enter appears like. Error messages ought to level to the subsequent 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’ve written about all this earlier than in additional depth when you’re .
The place to take a position
What I strongly consider is that there is no such thing as a single correct quantity of specification. The reply is dependent upon the form of work you’re doing. For a small, well-bounded process, the candy spot is normally structured intent: the objective, a couple 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 corresponding to CRUD flows, API integrations, and knowledge transformations, the optimum strikes to the appropriate. These domains are straightforward to constrain and straightforward to check. Extra specification pays for itself rapidly as a result of it cuts repeated evaluate and rework. That is the place BDD, contract exams, and executable acceptance standards assist most.
For exploratory work corresponding 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 have to 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 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 components simpler to separate from the components 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 introduced 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 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 could 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 evaluate nonetheless issues. Working software program continues to be higher than progress theater as a result of brokers can generate a variety of convincing wrongness in a short time. In reality, I might argue that quick suggestions issues extra now, not much less. If a group can go from imprecise concept to massive implementation in a morning, it additionally wants a technique to uncover by lunchtime that the thought was fallacious.
XP survives even higher as a result of it was all the time about retaining studying near the code. Take a look at-first pondering 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 couple of exams, and nonetheless leaves you with a construction no person needs to take care of subsequent month. The machine has no delight right here. It’s going to generate a large number with good confidence.
Pair programming modifications form, however the core concept survives. I nonetheless need design judgment near code technology. Generally that appears like a human working straight with one coding agent. Generally it appears like one mannequin producing code whereas one other mannequin critiques it with a narrower temporary. 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 massive modifications cheaply, the temptation is to just accept very massive diffs cheaply too. That could be a unhealthy concept. Assessment, rollback, and analysis are simpler completed in small batches. A brief-lived function department is less complicated 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 after they made it cheaper to find that the group understood the issue badly. That’s nonetheless the job. The agent period simply removes a couple of excuses and provides new methods to be fallacious at excessive velocity.
The actual 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 develop 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, after they want an actual contract, and when the contract has to develop into executable.
The brokers are getting higher. The choices are nonetheless ours.
