Agentic Development: Finding the Right Spec Sweet Spot

The rise of AI agents is dramatically changing the landscape of software development. With code generation becoming increasingly inexpensive and fast, a common temptation emerges: simply give a model a high-level goal, let it explore, and iterate through corrections. This 'zero-spec' approach often feels efficient initially, but it deceptively hides significant downstream costs. The reality is that someone still needs to serve as the 'oracle,' reviewing outputs, clarifying intent, requesting changes, and ensuring the result truly aligns with the original goal. This leads to costly, time-consuming correction loops.

At the other end of the spectrum, full formal specifications, including comprehensive acceptance criteria, contract tests, or Behavior-Driven Development (BDD) scenarios, are undeniably expensive upfront. However, they shift the burden, making more of the 'oracle' executable. Automated tests consistently check conditions without human fatigue or bias, drastically reducing downstream review and rework. The fundamental trade-off isn't whether specification is good or bad, but rather where the minimum total cost lies. For most agentic work, the optimal approach is a balanced middle ground: enough structure to guide the agent, sufficient examples to clarify intent, and enough executable checks to transform human review from guesswork into focused validation.

The Shifting Bottleneck of Software Engineering

Software engineering has always been less about typing code and more about strategic decisions: defining what needs to exist, what must be prevented, balancing trade-offs, and confirming what 'done' truly means in a real-world context. Historically, missing specifications often surfaced through human friction – a reviewer catching an edge case, QA discovering an undocumented path, or a senior engineer holding implicit requirements. This wasn't elegant, but human slowness inadvertently forced ambiguities into the open.

Agents fundamentally alter this dynamic. They make implementation cheaper and faster, allowing an underspecified idea to rapidly evolve into a plausible system before its true meaning is universally agreed upon. Where vague requirements once encountered human delays, they now run into machine speed. This acceleration highlights why precise specification is becoming critical again; it was always important, but implementation cost used to be a crude, implicit forcing function for clarity.

As automation increases and implementation effort decreases, the primary engineering difficulty shifts. The challenge is no longer just writing code, but rigorously defining 'correctness' and building reliable mechanisms to verify it.

Validating the Specification Itself

One of the most frequently skipped steps in agentic development is validating the specification. It's not enough to merely write a spec; it needs thorough review. Even a carefully crafted spec can suffer from common flaws: internal contradictions, incomplete coverage (e.g., ignoring retries or partial failures), describing untestable behavior, or being precisely accurate to the text but failing to capture the intended meaning. When an agent faithfully executes a flawed spec, diagnosing the resulting issues becomes significantly harder. The generated implementation may appear coherent and even pass provided checks, but the root problem lies upstream in the spec, requiring a complex unwinding of both code and reasoning.

To address this, spec validation warrants its own dedicated phase. Before implementation begins, key questions must be asked: Is the spec internally consistent? Is it sufficiently complete for the task? Which parts are testable? Where does human judgment remain crucial? What common failure modes are implicitly assumed and thus missing?

Agents themselves can assist in this validation process through a multi-agent workflow:

1. Specification Draft: Prompt one agent to Draft the smallest spec that would let another agent implement this safely. Include assumptions, nongoals, acceptance criteria, edge cases, observable outcomes, and open questions. Mark which claims can become automated tests and which still require human review.
2. Spec Attack: Hand the draft to a different agent with instructions to Find contradictions, ambiguous terms, hidden dependencies, untestable claims, missing failure modes, and places where an implementation could pass the written criteria while still violating the intent.

This workflow significantly lowers the cost of achieving a spec robust enough for meaningful human review.

Stronger Contracts for Multi-Agent Systems

While a single agent tackling a bounded task can often recover from loose instructions due to a tight loop and local blast radius, multi-agent systems present a different challenge. When one agent's output becomes another's input, interpretive drift can compound rapidly. Agent B, unaware of Agent A's slight misinterpretation, treats the input as ground truth and proceeds. By the time a human observes the final result, the initial error might be buried under layers of seemingly competent work.

In such scenarios, the spec evolves from mere guidance to a crucial contract. This contract demands more than just a paragraph of intent. It necessitates precise schemas, invariants, explicitly defined ambiguity, rigorous validation rules, and clear failure behavior. Often, this extends to contract tests, strongly typed interfaces, and machine-checkable handoff formats. The handoff itself becomes a product artifact, reinforcing the value of methodologies like BDD and executable acceptance tests which transform human-driven validation into repeatable, automated checks.

The Ephemeral Nature of Specifications

However, there's a point where pushing further on the specification curve becomes counterproductive. More text isn't always safer, especially with current AI models. Research like Chroma's work on context rot demonstrates that model performance can degrade as input size increases, even for simple tasks. In coding projects, an additional problem arises: the more design prose, examples, plans, comments, and outdated acceptance criteria you cram into the context, the harder it becomes to discern active instructions from historical artifacts. This isn't a security vulnerability but rather a self-inflicted 'instruction drift.'

When the context includes old design intent, current implementation details, partially valid examples, and stale documentation, the model attempts to average across competing sources of truth. Overspecification then stops being helpful and starts confusing the agent, which can no longer distinguish between an active requirement, a historical note, or something already superseded by code. A design document is valuable early on, but it needs to shrink as the code matures. Once interfaces, tests, and invariants are real, the detailed build plan should recede. Specs should focus on what code struggles to express: business rationale, non-goals, safety constraints, external contracts, and critical invariants that shouldn't be rediscovered. Redundant prose that merely restates what classes and methods already do should be eliminated; otherwise, you end up maintaining two conflicting 'specs.'

APIs as Living Specifications

There's an optimistic angle to this discussion: some codebases reach the 'code is the spec' ideal faster than others, largely due to strong API design. If an internal API conceals behavior behind implicit conventions, weakly typed parameters, setup magic, and generic errors, an agent cannot treat the code as an authoritative spec. It's forced to reconstruct rules from disparate prose and trial and error, which is slow for humans and even worse for models.

Conversely, an API designed with explicit names, task-level methods, strong types, readable validation, useful examples, and actionable errors provides agents with a concrete foundation. If an agent can easily inspect the API surface, understand method functionality, identify legal inputs, and recover from errors without guessing, the code itself shoulders much of the specification burden. This is the essence of AI-friendly API design: explicit discoverability over convention. Methods should align with real-world tasks, types and validation should clearly define legal inputs, and error messages should guide toward the next fix, not just announce failure. Introspection and clear examples help models learn the API's shape directly from the codebase. Performance transparency also matters, preventing agents from creating correct but inefficient loops around expensive calls due to lack of information.

This principle extends beyond public SDKs to internal service boundaries, library clients, repository abstractions, and even helper classes within large monorepos. The more discoverable and inspectable an API, the easier it is for an agent to treat the code as the authoritative spec, reducing the need for additional, potentially conflicting prose.

Investing Wisely: The Varying Sweet Spots

There is no single 'right amount' of specification; it is highly dependent on the nature of the work. The sweet spot, where total cost is minimized, varies:

• Small, Bounded Tasks: Here, structured intent is usually optimal: a clear goal, a few examples, defined nongoals, and explicit acceptance criteria. This balances agent productivity with minimal setup overhead.
• Deterministic Work (CRUD, API Integrations, Data Transformations): These domains are easily constrained and tested. More specification pays for itself quickly by reducing repeated review and rework. BDD, contract tests, and executable acceptance criteria are highly beneficial here.
• Exploratory Work (Architecture Options, Research, Novel Ideas): Over-specification can stifle the very flexibility that makes agents valuable in exploration. For such tasks, specifying boundaries is more effective than outcomes: define what must be true, what must not happen, required evidence, and which decisions still require human judgment.
• Multi-Agent Pipelines: The optimal approach shifts towards robust contracts at every boundary between agents. Without these explicit contracts, you're not coordinating a system; you're merely stacking interpretations and hoping for serendipitous alignment.

The overarching rule across all these scenarios remains: always validate the specification before scaling the implementation.

Enduring Wisdom from Agile and XP

Agentic development doesn't render Agile or XP obsolete; rather, it highlights their most valuable components. The casualties are mostly the ceremonial aspects designed for hour-by-hour human coordination, such as rigid daily status meetings or inflated backlog rituals, which become less relevant as agents rapidly reshape tasks. Effort estimates, too, become fictional even faster.

What truly survives from Agile is its core feedback logic. Short cycles, thin vertical slices, and continuous stakeholder review remain crucial. Working software still trumps 'progress theater,' especially since agents can generate a lot of convincing but incorrect code rapidly. Fast feedback is now more critical; if an idea can go from vague concept to large implementation by lunch, a team needs to discover its flaws by dinner.

XP's principles endure even stronger because it emphasizes learning close to the code. Test-first thinking is invaluable as implementation becomes cheaper, making executable checks paramount. Continuous Integration is essential as every agent-driven change needs a reliable gate. Refactoring remains vital because agents, without 'pride,' can generate functional code that passes tests but is a maintenance nightmare. Pair programming evolves but its essence of fast design judgment near code generation persists, whether it's human-agent collaboration or agent-agent review. Small releases also remain important; while agents make large changes cheap, large diffs are still harder to review, rollback, and diagnose. The value of methodology shifts from reassurance to error detection. Agile and XP excelled at making it cheaper to discover misinterpretations of the problem – a job that is more important than ever in the agent era.

The Real Leverage Point

Agentic development holds immense promise, significantly reducing implementation costs. However, as code becomes cheap, the ultimate success or failure of projects hinges on the quality of specification and verification. The teams gaining the most leverage won't be those that specify the least, but those who intelligently discern when three bullet points suffice, when a formal contract is necessary, and when that contract must be fully executable. Agents are indeed improving rapidly, but the critical decisions about scope, clarity, and validation remain firmly in our hands.

FAQ

Q: Why is the role of a 'human oracle' becoming more critical in agentic development?

A: As AI agents make code cheaper and faster to produce, the bottleneck shifts from writing code to defining what 'correct' means and reliably verifying it. Without precise specifications, a human is constantly needed to review agent output, clarify ambiguities, and guide the agent back to the true intent, effectively becoming a perpetual 'oracle' in a costly feedback loop. Stronger specs reduce the need for constant human intervention by making more of the 'oracle' executable through automated checks.

Q: How do specification needs differ between single-agent tasks and multi-agent systems?

A: For single agents on bounded tasks, structured intent (goals, examples, acceptance criteria) might be sufficient. The feedback loop is tight, and human steering is easier. However, in multi-agent systems, where one agent's output feeds another's input, even small interpretive drifts can compound. This necessitates much stronger contracts between agents, including schemas, invariants, validation rules, explicit failure behaviors, and often contract tests and typed interfaces, to ensure consistent understanding and prevent cascading errors.

Q: Does the rise of agents mean we can finally abandon Agile and XP methodologies?

A: No, rather than becoming irrelevant, agents highlight the most valuable aspects of Agile and XP. The feedback logic—short cycles, thin slices, continuous stakeholder review, and working software—becomes even more critical for rapidly discovering errors. Practices like test-first thinking, continuous integration, refactoring, and small releases are essential for managing the speed and scale of agent-generated code. What fades is the ceremonial overhead of these methodologies, while their core principles for error detection and continuous learning remain paramount.