Markus Eisele observes a recurring idea in discussions about agentic development: detailed specifications are seen as outdated overhead. Give a model a rough goal, let it iterate, fix what comes back — it appears efficient but hides real costs.
A short prompt looks attractive because it starts implementation immediately. In practice, however, correction loops follow: review output, clarify intent, request changes, rerun tests, find the next gap, and repeat. Someone still must decide whether the result matches the true objective — that person becomes the "oracle."
At the other extreme, full formal specification requires substantial upfront effort. Writing acceptance criteria, contract tests, or behavior-driven development (BDD) scenarios takes time. The downstream cost profile differs: executable checks move part of the oracle into automation. A test verifies the same condition consistently, unaffected by fatigue or last-minute optimism.
The real trade-off is not whether specification is inherently good or bad, but where total cost is minimized. For most agentic work the optimal point lies in the middle: enough structure to constrain the task, enough examples to make intent concrete, and enough executable checks to prevent review from becoming guesswork. Zero-spec is not lean intelligence — it’s costly vibe-coding.
The bottleneck moved, it didn’t vanish
Software engineering was never only about typing or producing code; it has always been about deciding what should exist, what should not occur, which trade-offs matter, and when a problem is truly "done" in the real world. Historically, missing specification surfaced through human friction: a reviewer found an edge case, QA discovered an undocumented path, or a senior engineer carried requirements in their head.
Agents change that dynamic by making implementation much cheaper and faster. A vaguely specified idea can become a plausible system before anyone has agreed on meaning. In the old world, human slowness acted as a brake; in the agent world, machine speed accelerates delivery. That shift makes specification feel important again. As implementation cost drops, more difficulty moves into defining correctness and checking it reliably.
Writing the spec is not enough
A commonly skipped step is spec validation. Even a careful spec can fail: it may contradict itself, document only the happy path, omit retries or rate-limits, describe behavior that is not verifiable, or be precise about what was written rather than what was intended.
When an agent faithfully executes a flawed spec, diagnosing failure becomes harder because implementation may look coherent and even pass provided checks while the real issue lies upstream in the spec. For that reason spec validation deserves explicit effort. Before implementation, someone should ask plain questions: Is the spec internally consistent? Is it complete enough for this task? Which parts are testable? Where do we still rely on human judgment? Which failure modes did we silently assume away?
Agents can help, but not when asked simply to "write requirements." Such prompts usually yield polished ambiguity. A more effective prompt is specific: 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 require human review. Then hand that draft to a different agent with instructions to attack it: find contradictions, ambiguous terms, hidden dependencies, untestable claims, missing failure modes, and places where an implementation could satisfy written criteria but violate intent. Even this modest workflow lowers the cost of reaching a spec worth human judgment.
Agents do not remove the need for specs; they make it cheaper to reach a useful level of specificity.
Why multi-agent systems need stronger contracts
A single agent on a small, bounded task can often recover from loose instructions: the loop is tight, the blast radius limited, and a human can steer it back. Multi-agent systems are different. Once one agent’s output becomes another’s input, interpretive drift compounds. Agent B will not notice that Agent A misunderstood a requirement by 10% — it treats the input as ground truth and continues. By the time a human inspects the result, the original mistake may be buried under several layers of competent-looking work.
At that point a spec becomes more like a contract. It requires more than a paragraph of intent: schemas, invariants, allowed ambiguity, validation rules, and explicit failure behavior. Often contract tests, typed interfaces, and machine-checkable handoff formats are necessary. The handoff itself is part of the product — less glamorous than imagined, but closer to reality.
This is where BDD and executable acceptance tests matter: they move part of the human oracle into repeatable automation. When behavior can be specified precisely, an executable spec is often cheaper than another round of human review. Once agents hand off work to other agents, the handoff must be specified and validated like a real interface.
A spec should have an expiration date
Another common error is treating more text as always safer. For current models that is false. Longer input degrades model reliability, even on simple tasks. In code projects there’s an additional risk: stuffing design prose, examples, plans, comments, tickets, and old acceptance criteria into the context blurs which parts are active instructions and which are artifacts.
This isn’t prompt injection in the security sense; it’s self-inflicted instruction drift. The context can contain old design intent, stale examples, generated plans from prior sessions, and documentation that references classes that no longer exist. The model then averages across competing sources of truth. Overspecification stops helping and starts to confuse: an agent can’t tell whether a paragraph is an active requirement, historical note, or something the code has already replaced.
Therefore design documents are useful early, but they should shrink over time. Once interfaces, tests, and invariants are real, detailed build plans should be pared back. Keep business rationale, non-goals, safety constraints, external contracts, and the few invariants you don’t want rediscovered by trial-and-error; delete prose that merely restates what code already expresses. Otherwise you end up with two specs: humans complain during review, and agents will often try to obey both.
APIs can make code behave like a spec
There is an optimistic path: some codebases reach the "code is the spec" point faster, and API design is a major factor. If an internal API hides behavior behind conventions, weak typing, setup magic, and generic errors, an agent cannot treat code as the spec and must reconstruct rules from scattered prose and experimentation.
Conversely, an API with explicit names, task-level methods, strong types, readable validation, useful examples, and actionable errors gives the agent something concrete. If the agent can inspect the surface, see what a method does, understand legal inputs, and recover from errors without guessing, the code carries more of the specification burden. AI-friendly API design matters in practice: explicit discoverability beats convention, methods should map to real tasks, types and validation should show legal input, error messages should indicate the next fix, and introspection and examples help the model learn the API shape. Performance transparency also matters so agents don’t write correct but costly loops around expensive calls.
This applies to public SDKs and to internal service boundaries, library clients, repository abstractions, and helper classes in a monorepo. The easier an API is to discover and inspect, the easier it is for an agent to treat code as authoritative spec rather than dragging more prose into the context.
Where to invest
There is no single right amount of specification; the answer depends on the work:
- For small, well-bounded tasks, the sweet spot is structured intent: the goal, a few examples, nongoals, and clear acceptance criteria.
- For deterministic work (CRUD flows, API integrations, data transformations), the optimum shifts right: these domains are easy to constrain and test, so more specification often pays back quickly. BDD, contract tests, and executable acceptance criteria help most here.
- For exploratory work (architecture options, research synthesis, novel product ideas), the optimum shifts left: over-specification can kill the flexibility that makes agents useful. Specify boundaries rather than outcomes: what must be true, what must not happen, what evidence is required, and which decisions require human input.
- For multi-agent pipelines, the optimum shifts right again: every boundary requires a contract.
Across all four cases the common rule is simple: validate the spec before scaling implementation.
What survives from Agile and XP
Agents don’t make Agile or XP irrelevant; they clarify which parts were useful and which were tolerated overhead. Coordination ceremonies that existed to sync human effort hour-by-hour (daily status, inflated backlog rituals, overconfident estimates) become weaker. Planning doesn’t disappear, but it must stop pretending it can reliably predict implementation cost as it did when code was the slow part.
What endures is feedback logic: short cycles, thin vertical slices, stakeholder review and working software still matter — perhaps more now, because agents can generate lots of convincing wrongness quickly. XP survives well: test-first thinking, continuous integration, and refactoring remain valuable, since executable checks gain importance as implementation costs fall and agents can produce code that works but is unmaintainable.
Pair programming changes form but not intent: design judgment should remain close to code generation, whether that means a human working with a coding agent or one model generating code while another reviews it. Small releases also remain important because review, rollback and diagnosis are simpler in small batches.
Methodology as reassurance fades; methodology as error detection survives.
The real leverage
Agentic development is a real promise: agents can make implementation dramatically cheaper. But once code is cheap, specification and verification determine project success or failure. The teams that win will not be those that specify the least; they’ll be the teams that understand when three bullets suffice, when a real contract is needed, and when that contract must be executable.
The agents are improving — the decisions remain ours.
— Markus Eisele (based on the original piece)
