Software Specification Formats for AI-Readable Requirements

A spec that says "validate the payment input and return an error if invalid" sounds complete enough. An AI coding agent will read that line and produce a function that returns a boolean, or throws an exception. It'll pass a basic test. Then a downstream UI tries to display which field failed, or a retry system needs to tell a card expiry error apart from a bad CVV, and the whole thing breaks.

That gap between "passes a test" and "works in production" is the entire problem with vague requirements. A human developer facing that same sentence would ask a question: which field failed? What does the error object look like? AI agents don't do that. Research on this behavior (the Ambig-SWE work) documents a clear asymmetry, showing agents proceed on incomplete understanding, filling gaps with assumptions instead of asking. That's a structural fact about how these systems operate, not a quirk to route around with better prompting, and it means every ambiguous sentence in a spec becomes a guess baked into shipped code.

The damage compounds. The Specine research found that when a spec is misread or underspecified, the error doesn't stay contained. It propagates through planning, through task breakdown, through implementation, because each downstream stage inherits the agent's flawed read of the previous one. An inaccurate perception of the spec at step one narrows what's even possible to fix at step five.

This is the mechanism that made "vibe coding" (building from quick, unstructured prompts) fine for a weekend project and dangerous for a production system. Devoteam's analysis of the pattern is blunt about it: vibe coding works at small scale, but in a complex corporate environment it fails quietly, leaving behind implicit decisions nobody remembers making and inconsistencies between components that surface much later.

Models keep getting better, so it's fair to ask whether this problem will shrink on its own, but the evidence says no, at least not fast enough to matter. Even on SWE-Bench Pro, a benchmark specifically built to resist contamination and test harder problems, scores drop sharply compared to easier benchmarks. Model improvement just moves the goalposts on what "vague" means, without erasing the need for precise behavioral constraints. The fix is a spec built so there's nothing left to guess, not a smarter model reading a sloppier spec.

The spec's shift from reference document to operational contract

That fix has a name: Spec-Driven Development, or SDD. Under this model, the Software Requirements Specification stops being a static document that humans consult before or during a project. It becomes an operational contract that actively governs what an agent builds.

To see how far that is from the original design, it helps to look at what the SRS was built for. The standard most teams still reference, ISO/IEC/IEEE 29148 (which replaced IEEE 830 back in 2011), was written to give human stakeholders, product owners, developers, testers, a shared baseline before work started. It assumed a human would read it, interpret it, and fill in the small gaps using judgment and context. That assumption breaks with an AI agent as the reader. By 2026, the SRS increasingly functions as structured input for AI coding agents, not simply a reference document sitting in a shared drive.

Devoteam's framing of the shift uses a clean analogy: the spec becomes the artifact, and the code becomes the build output, the same relationship a .c file has to its compiled binary. Edit the spec to change the behavior, and automated systems regenerate the code from there. Under this model, a workable machine-readable spec needs to nail down what the system must do, the specific conditions under which that behavior counts as correct, and how to check that behavior automatically.

The urgency here isn't theoretical. Multiple specialized agents often work in parallel on the same codebase, and without a shared conceptual anchor, they optimize their own piece in isolation and lose sight of the whole. Devoteam's analysis ties this directly to invisible patches, redundant code, and architectural drift across a project. Birgitta Böckeler at Thoughtworks put the emerging definition simply: spec-driven development means writing a spec before writing code with AI, documentation first. The spec becomes the source of truth for the human and the AI both. The arXiv taxonomy paper (arXiv:2606.04967, June 2026) confirms the same pattern across six frameworks: the single isolated prompt loses its central role, replaced by persistent artifacts, explicit work contracts, traceability between spec and code, and human review checkpoints, the mechanisms that reduce ambiguity and keep multiple agents coordinated.

What the EARS notation does that prose requirements cannot

If the spec is now a contract, it needs a syntax that reads like one. That's what EARS, the Easy Approach to Requirements Syntax, provides. It has become the dominant notation for AI-readable requirements because each of its five patterns forces a requirement down to one testable claim, with no room left for guessing at scope, trigger, or response.

Take a typical prose requirement: "The system should validate payment input and typically return an error if something's wrong." A human reader fills in "typically" without noticing. An agent doesn't have that context to fall back on, and it will produce something plausible but potentially wrong. Rewritten in EARS, an event-driven pattern, that requirement becomes something closer to: "When the payment form is submitted with an invalid card number, the system shall return an error object identifying the specific field and reason." Every part of that sentence is checkable. The trigger is explicit (form submitted with invalid card number). The response is explicit (error object, specific field, specific reason). Nothing is left for the agent to infer, and a test can be written directly against it.

The five patterns cover the full range of behavior a spec needs to describe: Ubiquitous, for behavior that's always on; Event-Driven, for behavior triggered by something happening; State-Driven, for behavior conditional on the system's current state; Optional, for features that only apply under certain conditions; and Unwanted Behavior, for how the system responds when something goes wrong. EARS substitutes hard imperatives and measurable values in their place.

None of this requires teams to standardize on EARS specifically. Given/When/Then (Gherkin) syntax and structured input/output tables accomplish the same goal through different formatting. What matters is that the requirement resolves to a binary pass or fail. The specific notation matters less than the discipline of eliminating any space for interpretation.

Well-written requirements have always aimed to avoid ambiguity, so it's fair to ask what's different now. Prose that reads clearly to a human can still leave trigger conditions, state boundaries, and response details implicit, because a human reader supplies them from context automatically. An agent needs all three spelled out directly in the syntax, not inferred from surrounding sentences.

The four structural elements that make a spec genuinely executable

Notation solves half the problem. The other half is what sections a spec actually contains. An executable AI spec needs four elements as a baseline. Acceptance criteria must be built around concrete inputs and outputs, alongside machine-readable input/output contracts, an explicit boundary marking what's out of scope, and a declared tech stack down to the version number. Skipping any one of these leaves a gap that the agent fills with an assumption it invented.

Acceptance criteria have to describe concrete inputs and outputs, not general behavior. Augment Code's spec template guidance identifies this as the single section that prevents the most failures. Gherkin's Given/When/Then format is one workable way to write these. A 2025 study by Fonseca, Lima, and Faria measured automated Gherkin generation from natural-language JIRA tickets at BMW and found practitioners reporting time savings often equal to a full developer-day per feature, with the generation itself finishing in under five minutes. A separate study by Hassani, Sabetzadeh, and Amyot found that a strong majority of quality ratings for LLM-generated Gherkin specifications, specifically on the time-savings measure, landed in the top two categories.

Input/output contracts solve a narrower but equally damaging problem: agents can't reliably infer data types from a prose description. A schema written in JSON Schema, Zod, or OpenAPI constrains what the agent can output without dictating how it gets there. Return to the payment example from the opening: a Zod schema that defines cardNumber as a string matching a 13-19 digit regex eliminates the class of failures where an agent infers a numeric type and breaks on leading zeros.

An explicit "Not Included" boundary handles a different failure mode entirely. Left without one, agents tend to add features that seem reasonable in isolation but were never asked for, the same behavioral asymmetry documented in the Ambig-SWE research: humans clarify, agents proceed and assume. Pairing a tight, singular objective, one to three sentences, with a "Not Included" section gives that objective an enforcement mechanism instead of just a hope.

Tech stack declarations close the last gap. A spec that says "use React" without a version number can produce code that mixes React 18 patterns with React 19 APIs in the same file. Tools have started building version discipline directly into their workflow: AWS Kiro maintains steering files under .kiro/steering/ that hold conventions across sessions, and GitHub Spec Kit stores its structured artifacts in a .specify folder for the same reason.

What belongs outside the spec matters just as much as what goes in. Implementation hints, pseudo-code, and vague quality language either box the agent into one approach or reintroduce the same ambiguity the rest of the document was built to remove.

How the leading SDD frameworks operationalize these structural requirements

These four elements aren't just a checklist teams write by hand. The current generation of SDD frameworks builds them into the workflow itself. Most share a four-phase gated structure, Specify, then Plan, then Tasks, then Implement, with a human checkpoint at each stage. Where they differ is in how strictly they enforce specification depth, how they track changes back to the code, and how well they travel across different agent runtimes.

A June 2026 taxonomy paper evaluated six of these frameworks, GitHub Spec Kit, OpenSpec, BMAD Method, Get Shit Done (GSD), Spec Kitty, and Reversa, against six dimensions: specification, context, roles, execution, validation, and portability. The finding that matters most for anyone picking a tool: no single framework covers all six dimensions strongly. There's a genuine trade-off between how deep a framework pushes on process and how portable it stays across different agents.

GitHub Spec Kit is open source and model-agnostic. It runs the four-phase gated workflow, with each phase producing a Markdown artifact saved into a .specify folder, treating the specification itself as the central artifact that feeds everything downstream. Its supported model list spans 28 models across OpenAI, Anthropic, Google, Microsoft, Moonshot AI, and xAI, including Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, and Windsurf.

AWS Kiro takes a different shape as an agentic IDE, separating the intent phase from the implementation phase and using steering files to hold conventions across a session. BMAD Method organizes planning, architecture, and implementation into phases handled by specialized agents, an agile planning approach built around agent roles. OpenSpec offers a lighter-weight version of the same idea, one of the six frameworks the taxonomy evaluated specifically for how well it balances process depth against portability.

Reversa approaches the problem from the opposite direction. Instead of starting from a written spec, it uses reverse documentation engineering to turn existing legacy software into an operational spec that agents can then read and build from, aimed squarely at the common enterprise problem of a codebase with no real documentation left.

Choosing among them comes down to what a team actually needs enforced. Compliance pressure raises the need for strong traceability between spec and code, so that concern matters most for those teams. Teams running across multiple agent runtimes need a framework that scores well on portability. Teams sitting on an undocumented legacy system have a clear reason to look at Reversa's reverse-engineering approach specifically.

Spec quality as the bottleneck over code generation speed

All of this points to a shift in where the real constraint sits. AI has pushed code generation speed to the point where fast output stops being a competitive edge, because everyone has it. The constraint moves to specification and verification instead, and treating spec work as overhead now means optimizing the wrong part of the process.

The DORA 2026 report states that as AI speeds up code generation, the bottleneck moves to specification and verification. Specs stop being overhead sitting on top of implementation and become the scarce resource the whole process runs on. Devoteam's analysis reaches the same place from a different angle: generating a complete feature in minutes is no longer an advantage, for it's the baseline everyone starts from. Control, not raw speed, is the challenge left standing.

That shift is easier to justify now that writing a solid spec doesn't cost what it used to. The BMW case from Fonseca, Lima, and Faria's 2025 study found automated Gherkin generation from plain-language JIRA tickets finishing in under five minutes per feature, work that used to take a full developer-day. Spec authoring isn't the expensive step anymore. The expensive step is what happens after a vague spec ships: agent correction cycles. Specification and system design failures make up one of three major failure categories in multi-agent LLM systems, and most of those correction cycles trace back to vague requirements, not to which notation or format the team happened to pick.

Context windows can overflow with current LLMs, as Takafumi Endo, CEO of ROUTE06, has pointed out, which pushes teams toward more compressed, structured document formats out of necessity. Format choice here has runtime consequences, not just readability ones.

Against all that, the objection "we move too fast to write detailed specs" doesn't hold up well. Tooling has already collapsed the time cost of writing a good spec down to minutes. What hasn't gone away is the cost of skipping one: correction cycles that stack up across a multi-agent session running for hours, each one tracing back to a sentence that should have been specific and wasn't.