Spec-driven development: a vague brief makes wrong code fast

When speed becomes the problem

An AI tool writes a function in seconds. Whether it wrote the right function is a different question, and the answer depends almost entirely on how clearly you described what you needed.

Last time we looked at why AI-generated code so often misses what you actually meant to build. The gap between "what the agent produced" and "what you needed" has a name: a specification problem. And it gets more expensive the faster agents get, because speed scales whatever you feed in, including the gaps.

A May 2026 preprint on arXiv found that as agents get faster, engineering discipline has to shift upstream to specification. When a spec is missing before work begins, the agent that builds and the process that checks it are working from the same unchecked assumption. They agree because they started from the same gap, and that agreement doesn't make the answer correct.

There's a subtle trap in this. When an agent finishes quickly and produces something that compiles and passes a basic test, the natural response is to accept it. The code looks right. The task is marked done. The real problem surfaces later, when the finished module meets the rest of the system and the assumptions don't fit. By then, the original brief has been replaced by the code itself as the record of what was intended.

With a human developer, a gap in the brief often gets caught in a conversation, a comment on a review, or a clarifying question before anyone writes a line of code. With an AI agent, those natural correction points don't exist unless you build them in, and building them in starts with the spec.

The software engineering body of knowledge, SWEBOK, addresses this under Software Requirements: the discipline of finding, writing down, and checking what a system must do before anyone builds it. That discipline existed long before AI agents. With agents, skipping it gets you to the wrong outcome faster, with more confidence, and with less of a paper trail to explain what happened.

What a spec actually is

A spec is a written contract. It says what the agent must build, what must stay true while it builds, and how you'll confirm the result is correct afterward. The agent implements the contract. A separate process checks whether the contract was met. Those are two different jobs, and keeping them separate is the point.

Think of it like a recipe you read completely before you touch the pan. A vague instruction ("make something warm and savoury") leaves the cook guessing at every step: which spices, which technique, which quantities, how long. A recipe that lists the ingredients, names the ones that can't be substituted, and describes what the finished dish should look and taste like leaves far less room for creative interpretation. The recipe is also specific enough that someone else could check whether the cook followed it. The spec exists before the agent starts. The check depends on the spec existing.

The word "separate" matters here. The process that checks the result must work from the same written contract as the process that built it, but independently. If both draw from the same vague brief, they'll arrive at the same wrong answer and agree it looks right. That agreement looks like a passing test. It tells you nothing useful.

Why the contract has to exist before the first file changes

A January 2026 paper on arXiv showed that vague specs cause AI agents to make unstated assumptions that surface as integration failures, rework, and teams discovering they each meant something different by "done." The problem is structural: a vague brief doesn't just mislead the agent. It also misleads the verification process, because both are drawing from the same gap.

This matters because AI agents don't pause to ask questions. A human developer reading a vague ticket might stop, raise a concern, or flag an ambiguity before writing any code. An agent makes the most plausible interpretation, builds something consistent with that interpretation, and produces a result that looks finished. By the time anyone realises the interpretation was wrong, the code has been reviewed, the original task is closed, and the brief has been forgotten. Retrieving intent after the fact is slow and unreliable.

There's also a subtler problem: a verification process that runs after the code is written will tend to test what was built, not what was needed. If the spec was vague, the test is written to match the code, and both go wrong in the same direction. An independent verification against a prior written spec breaks that circularity.

A written contract, reviewed and approved before any file changes, is what prevents that sequence. A prompt typed at the start of a task is an instruction to a specific agent. A spec is a commitment that both the builder and the checker can be held to, regardless of which process runs them.

The three things a spec has to say

A useful spec for an AI agent works at three levels. A gap at any level leaves the agent to fill it independently, and an agent's independent decision looks identical to a deliberate one after the fact.

1. Intent: what to build. This is the goal, stated as a problem to be solved. Keep it at the level of the problem, before any solution decision is made. "Users should be able to reset their password without contacting support" is intent. "Add a forgot-password endpoint" has already made a design decision inside the requirement, and the agent will build to that decision rather than the underlying need. The intent section keeps the agent pointed at the problem. The agent determines the approach; the spec's job is to be precise about the problem itself.

2. Constraints: what must stay true. These are the rules that apply regardless of how the agent solves the problem: which parts of the system must remain untouched, which external services it may call, how much it's allowed to do on its own. The OWASP guidance on large language model applications (the 2025 edition addresses this under "Excessive Agency"): an agent that can do more than its task requires can cause damaging actions that nobody planned for. A constraints section is how you keep the agent's reach inside the boundary of the task, before it begins. Constraints also give the verification process something to check independently. If the spec says the agent must stay within a defined part of the system, the verifier can confirm it did. A constraint that exists only in someone's head is a constraint that never gets checked.

3. Criteria: how to confirm it's done. These are the checks a separate process can run after the agent finishes, to verify the contract was met. They need to be specific enough for a machine to evaluate. "It should work" is a hope. "A user with a valid email address can request a reset link, receive it within 60 seconds, and use it exactly once" is a criterion: something that either passes or fails. Criteria are what make verification independent of the agent's own judgment about its work. An agent that writes both the code and the test for that code will pass every time, which proves nothing.

Together, the three levels form a chain. Intent defines the problem to be solved. Constraints define the boundary within which it gets solved. Criteria define what a correct solution looks like when you check it independently. A well-written spec doesn't just guide the agent; it gives the reviewer something specific to approve, the verification process something specific to run, and the team something to point to when the result is questioned.

How the approval step closes the loop

Writing the three levels down is necessary. A reviewed and approved spec is the step that makes it mean something.

Every change starts as a written spec, reviewed by a person before a single file changes. That review asks three questions: does the intent match what the team actually needs, do the constraints cover the relevant risks, and are the criteria specific enough to run automatically without interpretation. Only after those questions have answers can the agent begin.

The review also acts as a forcing function. When you write the intent down and ask someone to approve it, ambiguities surface before any code is written. A constraint you thought was obvious turns out to be unclear. A criterion you assumed was measurable turns out to be a judgment call. These are the gaps that become assumption bugs when the agent fills them in on its own.

This is different from reviewing finished code, which checks whether the code is correct. A spec review checks whether the plan is right before any code exists. The two questions aren't the same, and they shouldn't be answered in the same pass.

One addition that's easy to skip: consulting a record of past mistakes before each plan is finalised. An agent has no memory of the last time a similar spec produced an unexpected result. A written list, read before each plan, does the remembering. Over time, that list becomes one of the more useful assets in the process: a catalogue of the gaps that looked like non-issues until they weren't, and a reference for tightening constraints or sharpening criteria before the next task starts.

The May 2026 arXiv paper describes this arrangement as the defining new stage in an AI-native development cycle: independent, multi-agent verification followed by human sign-off, with the specification as the primary artifact. The code is a consequence of the spec. The spec is what gets reviewed, approved, and kept. That inversion of emphasis is the shift.

One real example

In my own projects, each agent task begins with a written spec covering intent, constraints, and criteria, reviewed and approved before the agent touches any file. A list of past mistakes, now more than 380 entries long, is consulted before each plan is finalised. The list exists because gaps in earlier specs produced results that looked finished and turned out not to be. Writing each instance down is cheaper than encountering the same gap a second time.

The short version

A spec is a written contract with three parts: intent says what the problem is, constraints say what the agent must stay within, and criteria say how you'll confirm the work was done correctly. The contract is written and approved before any file changes. A separate process checks the result against the criteria independently, so that agreement between builder and checker reflects the contract and not a shared assumption that nobody questioned.

If the agent that builds and the process that checks are both starting from the same vague brief, their agreement tells you nothing useful.

How do you currently decide that an AI-generated change is actually done?

Sources

• Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants, arXiv, 30 Jan 2026
• SDAD: Spec-Driven Agentic Development for the AI-Native SDLC, arXiv, 5 May 2026
• SWEBOK v4, Software Requirements: covers how requirements are elicited, specified, and validated through reviews, prototyping, and simulation, bearing on why treating specification as an engineering discipline matters before any agent task begins.
• OWASP Top 10 for LLM Applications 2025, LLM06 Excessive Agency: covers how granting an agent more functionality, permissions, or autonomy than its task requires can enable damaging actions, bearing on why explicit scope constraints belong in every agent specification before any file changes.