How AI Coding Agents Consume Gherkin Scenarios to Generate Code

AI coding agents use Gherkin scenarios both to tell them what software to build and to test what they build. That dual role is the point. A well-written .feature file tells the agent what to aim for and when to stop, while a weak one lets it claim success after solving the wrong problem. The difference depends less on clever prompting than on clear behavior, executable checks, and human approval.

Why Gherkin's structure makes it useful as agent input in ways prose specifications cannot match

“Add login” leaves an agent to fill in the blanks. A concrete Gherkin scenario instead declares the starting conditions, the action, and the expected result, such as Alice logging in with valid credentials and gaining access to her dashboard. Given establishes context, When names the action, and Then states the outcome. An agent no longer has to pull that relationship out of a paragraph where requirements, suggestions, and ideas for implementation share the same sofa.

That structure separates behavior from the machinery that produces it. A declarative scenario says what must happen without prescribing storage choices or a sequence of button clicks. Gherkin was designed so business analysts, developers, and QA could read the same artifact, and that shared language also gives agents usable instructions. Well-written scenarios therefore serve as living documentation, acceptance criteria, and automated test input, without requiring separate versions of what “correct” means.

How Gherkin works in two directions at once as build instructions and verification oracle

Those acceptance criteria give the same file two directions of travel. Going into the agent, the scenario specifies what to implement. Coming out, it supplies the expected behavior against which the implementation is checked. An oracle is simply the judge of correctness. Here, that judge is not another confident paragraph from the model but an executable statement of what the software should do.

Without a specification, an agent can generate code and tests from the same mistaken reading of a prompt. The code handles the requirement incorrectly, and the tests congratulate it for doing so. Everyone agrees, which is precisely the problem. Human-authored Gherkin that predates implementation breaks this self-confirming loop by supplying intent the agent did not invent. Unit tests can check whether a function returns its expected output, while behavior-driven development scenarios check whether the application satisfies the user story.

With a sufficiently complete .feature file, the instruction becomes “implement features/authentication.feature and make all scenarios pass”. The agent reads the scenarios, generates an implementation, runs them, and revises the code until they pass. Cucumber, Reqnroll, the successor to the now-retired SpecFlow, and Behave can execute those scenarios through step definitions and report pass or fail. That verdict establishes correctness only against the specified examples, leaving behaviors the authors forgot to specify unverified.

The two technical channels agents use to consume Gherkin through context injection and retrieval

To act on that contract, agents need both the scenarios and enough surrounding context to interpret them. Context injection gives the agent rules for the project, such as a gherkin-guidelines.md file that says how scenarios should be written and understood. Those rules apply before any individual task begins. Feature files in features/ or specs/ can join that project context, so the agent receives behavioral requirements together with the discipline for reading them. This channel establishes the interpretation layer rather than searching for a fresh one on every request.

Retrieval-augmented generation, or RAG, handles a different job. It turns the current task into a search over relevant repository content, including feature files, existing step definitions, source code, domain models, and prior commit history. The repository becomes the agent’s working knowledge base. Retrieved chunks give it not just the scenario text but the implementation context needed to fit new behavior into existing code. When the available context window can hold the whole corpus, inline context or direct filesystem searches may suffice instead.

Step definitions link what these channels supply to tests that can run, and their role is easy to underestimate. Plain-language scenarios do not execute themselves, however persuasive the typography. Agents can generate the glue code that connects each step to a test, allowing product managers to write behavior while the agent supplies the wiring. Poth et al.’s 2026 paper, “Baseline Evaluation of LLM-Facilitated UI Test-Case Generation from Gherkin Specifications”, addresses this pipeline. The distinction is important because understanding a scenario and connecting it to an executable check are separate tasks.

How spec-driven development formalizes the Gherkin-as-oracle pattern into a full workflow

Spec-driven development, or SDD, makes the specification the source of truth from which implementation follows. Its workflow moves through Specify, Plan, Tasks, and Implement, with a human checkpoint at each phase. The spec changes before the code does. Versioning it with code, typically in specs/ or .specify/, gives the agent current intent.

Within that workflow, the plan is broken into atomic, independently shippable tasks. The agent runs Gherkin scenarios after each task, so acceptance checks keep catching regressions as the work goes on. This addresses more than a testing gap. Explicit specifications counter intent drift from vague prompts, repository-based context helps address context decay, and executable acceptance criteria make output verifiable. BDD starts with behavior written in business language, while full SDD adds architecture, edge cases, and constraints to the specification.

Deepak Babu Piskala’s technical report, “Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants”, describes increasing rigor through spec-first, spec-anchored, and spec-as-source approaches. These approaches differ in how strongly the specification governs implementation. GitHub Spec Kit, Kiro, and Claude Code give this workflow concrete tooling reference points. Spec Kit provides an open-source implementation, while Kiro is an agentic IDE built for SDD.

What BDD-Bench reveals about agent performance when Gherkin is used as the evaluation oracle

BDD-Bench finds that agents often pass visible scenarios but fail withheld variations of the same behavioral specification. Developed by Jagiellonian University, Exadel, and AGH University of Krakow and published at ACM AgenticDev’26 on 8 October 2026, the benchmark asks agents to implement executable Gherkin specifications at repository level. Its lifecycle mode follows consecutive tasks on an evolving codebase. Original tests are augmented with visible and hidden model-generated scenarios to assess coverage and generalization.

That gap exposes the limits of an oracle built around convenient examples. A green result is not a blank cheque. The benchmark shows why tests need to cover edge cases as well as happy paths. It also places evaluation in an evolving repository, where the question is not merely whether an isolated answer looks right but whether behavior holds as development proceeds.

Nasdaq AB’s case study shows how the same scenario-to-step-definition pipeline fits into a business. It describes a BDD test-case generation tool intended as a standalone service on the Nasdaq Gen AI platform, generating Gherkin scenarios and corresponding Python step definitions with LLMs. The previous work required testers’ time and specific domain knowledge. That case grounds the pipeline in a concrete organizational need, but it does not erase the benchmark’s warning. Generating more executable examples is useful only when those examples capture the intended behavior.

Why AI-generated Gherkin fails without explicit guidelines — and what that costs the oracle

The strongest objection to this pattern is also its central dependency. If the agent invents the scenarios it will satisfy, the independent judge can become its accomplice. Valid syntax offers no protection against that failure. A Then step such as “the system should return the correct results” looks like Gherkin but supplies no usable definition of correctness. The oracle has put on a referee’s shirt and forgotten the rules.

Without explicit guidance, generated scenarios can also become UI-heavy scripts, combine several behaviors, or fill example tables with placeholders. These failures weaken both directions of the contract. Vague outcomes leave build instructions open to interpretation, while multi-behavior scenarios blur the signal when verification fails. Imperative steps such as clicking the Login button and typing alice make the test depend on UI details. Declarative behavior such as Alice logging in with valid credentials and accessing her dashboard survives changes to those details.

This is a context problem as well as a model-capability problem. Without BDD rules, a model can copy patterns that look familiar without checking that they give concrete examples of behavior. Because Gherkin is readable by business stakeholders, the people who know the intended behavior can inspect it before implementation begins. The fix is deliberate context injection plus approval of scenarios before the coding agent uses them.

How to write Gherkin that agents use effectively as both build instruction and verification oracle

For teams adopting this pattern, the practical discipline begins with declarative authorship. Describe what should happen rather than which controls to click, so the agent can choose an implementation without changing the required behavior. Pair that with one behavior per scenario. A focused scenario gives the agent a clear target and makes a failed check easier to diagnose.

Describe the intended behavior in business language so stakeholders can catch intent drift before it becomes code. Then make behavioral variation explicit through error paths, out-of-range inputs, and concurrency cases where those belong to the requirement. The benchmark’s visible-versus-hidden gap shows why examples must expose the range of intended behavior rather than merely demonstrate that the easiest case works.

Acceptance traceability connects each approved user-story criterion to an executable scenario. That mapping shows what is tested and why, so the file tree does more than keep test assets in order. With a Gherkin guidelines file attached to project rules, no one has to remember to put the same instructions in every prompt. When humans approve the generated scenarios before implementation, those scenarios cannot quietly become permission slips the agent writes for itself.

Run scenarios after each atomic task so behavior is checked throughout implementation. The execution history then becomes an audit trail. Open-source, model-agnostic agent platforms running in team infrastructure support this pattern when they allow standing context files and make execution logs visible to the team. With those logs in view, organizations can see how approved behavior links to verification results and check the evidence before they automate more work.

Why the Gherkin-as-oracle pattern is becoming the foundation of agent-driven development, not just a testing practice

Continuous agent loops change the specification’s role from a document consulted occasionally to a contract used throughout development. Model Context Protocol, or MCP, extends that direction by connecting Gherkin repositories and step-definition libraries as live tool sources. Context engineering supplies the complementary discipline of selecting the right scenario and implementation context for each task. The agent needs a defined behavior, access to the code that supports it, and a check for completion.

Teams must maintain specifications with the same discipline as production code because agents operate against them continuously. Governance needs more than a passing test. It needs the connection between a human-approved scenario, the work performed against it, and the resulting verification record. Gherkin’s larger role is to make that connection readable and executable, so an organization can explain not just what its agents built, but why it accepted the result.