← Blog

Agile Writing User Stories for Parallel Coding Agents

9 Min. Lesezeit

Key takeaways

  • Write one testable behavior per story as Given-When-Then Gherkin criteria so the agent can verify done itself before opening a merge request.
  • Scope each story to named repos and paths with no overlap between sibling stories, so parallel agents never touch the same code.
  • For multi-repo stories, write acceptance criteria against the observable API contract, not implementation details.
  • Review agent merge requests against the pre-written Gherkin checklist instead of reading diffs cold, rejecting any touched file no scenario requires.
  • A vague story is the most expensive artifact in an agent pipeline; decide the behavior and write criteria before dispatching.

<!-- meta description: Agile writing user stories for parallel coding agents: Gherkin criteria, scope boundaries, and review checklists that keep concurrent agents from colliding. (155 chars) -->

Agile Writing User Stories for Parallel Coding Agents

Agile writing user stories for parallel agents means one testable behavior per story, written in Gherkin so each agent gets machine-checkable acceptance criteria instead of prose it can drift from. You scope stories so concurrent agents never touch the same code, and you review merge requests against the criteria rather than reading diffs cold. The rest of this piece shows how.

Why do generic user stories break down when a coding agent implements them?

A generic story assumes a human reader who asks clarifying questions, infers scope, and quietly fixes scope gaps. An agent does none of that. It takes the story literally and starts implementing, so every ambiguity becomes a confident, wrong decision made three repos away from where you are watching.

The cost is real. The Ticksly team runs up to thirty Claude Code and Codex sessions and pays roughly $8 per merge request at API prices, with "The three of us provide the tasks and the direction" (their own writeup). When the task is vague, you pay that $8 for the wrong implementation, then pay again for the retry.

The fix is writing stories as Gherkin acceptance criteria: one testable behavior per story, machine-checkable Given-When-Then steps, and nothing left for the agent to interpret. Structure like this is what stories for coding agents are built around, because a story an agent cannot misread is the cheapest orchestration tool you own.

How do you convert a user story into Gherkin acceptance criteria an agent can act on?

Keep the "As a... I want... so that" line, but treat it as intent, not instructions. The agent works from the acceptance criteria below it, so the conversion job is turning one fuzzy want into several Given-When-Then scenarios, each naming one observable behavior.

One scenario, one behavior

Split anything with an "and" in it. "Given the user is logged in, when they upload a CSV, then the preview renders and the row count appears" is two stories. An agent handed both will implement the first, half-implement the second, and report success. Each scenario should have exactly one trigger (the When) and one checkable outcome (the Then). If you cannot name the trigger in a sentence, the story is not ready for a parallel agent, and it will drift through a multi-repo codebase looking for something to do.

Make the outcome machine-checkable

This is the paragraph worth quoting: a Then that says "the system handles the request appropriately" gives the agent nothing to verify against, so it decides for itself what done means, and its definition will not match yours. Write outcomes a test or a reviewer can check mechanically: a status code, a file that exists, a row count, an error message with exact text, a merge request that touches only the paths named in the story. "Given the invoice total exceeds the credit limit, when the agent submits the order, then the API returns 422 with error code CREDIT_EXCEEDED and no order row is written." The agent can run that check itself before opening the merge request, and you can verify it in thirty seconds instead of reading the diff cold. More worked conversions are in our guides on working with AI coding agents.

How should stories be scoped when running several coding agents in parallel?

Split by behavior first, then by file and repo ownership. A story that touches five areas of the codebase is fine for one agent; it is a collision waiting to happen for four. The Gherkin criteria are not just acceptance tests here, they are the boundary contract: if a scenario in story A requires a change in a module owned by story B, the split is wrong.

Splitting the thinking from the doing

"Splitting the thinking from the doing is the whole trick. It is what keeps agents from wandering off into a big codebase and getting lost" (secondshiftdev on running four coding agents at once). In practice that means the human writes the story, the boundaries, and the scenarios before any session starts, and the agent only implements inside them. Left alone together, agents overwrite each other's work and duplicate effort, so the ownership boundary has to exist in the story text, not in your head.

One agent, one behavior, one merge request

Scope each story so its scenarios map to files one agent owns:

Story elementScope rule
BehaviorExactly one testable scenario set
Files/reposNamed explicitly; no overlap with sibling stories
Merge requestOne per story, verified against its criteria

If two stories share a file, merge them or extract the shared change first. Task trackers like Vibe Kanban and Linear can track the queue, but the scoping decision lives in the story itself. For a fuller breakdown of orchestrators and how they handle task distribution, see our guide to agentic AI coding tools.

What does Given-When-Then look like for a story that spans multiple repos?

Write criteria against the contract, not the code

When a story touches an API repo and a frontend repo, the mistake is writing criteria about implementation: "the endpoint validates the payload." An agent in the frontend repo cannot verify that, so it drifts or guesses. Write the criteria against the observable contract instead.

Scenario: Invoice status is available to the dashboard
  Given an invoice with status "overdue" exists
  When the dashboard requests GET /api/invoices/{id}
  Then the response body contains "status": "overdue"
  And the response code is 200

Now split the work by contract. The API repo's agent gets the slice it can verify locally: hit the endpoint, assert the response. The frontend repo's agent gets a mocked payload matching that exact shape and asserts on rendering. Each agent runs its own Given-When-Then in its own worktree, and neither needs to know the other exists.

The reviewer's job also changes. When both merge requests arrive, you check each diff against the same contract, not against two agents' differing interpretations of one vague sentence. If a payload field is renamed, exactly one scenario fails and tells you which repo broke the contract.

For the full template we hand to agents, see stories for coding agents.

How do Gherkin criteria speed up reviewing agent pull requests?

A Gherkin scenario is a review checklist you wrote before the agent started. Given-When-Then gives each scenario a fixed precondition, a trigger, and an observable outcome, so the reviewer's job becomes "does the diff satisfy these lines?" rather than "what was this agent trying to do?" You stop reverse-engineering intent from code you did not write.

This matters because agents drift confidently. One that "fixes the wrong thing for three hours" produces a plausible-looking diff; without criteria, the only defense is reading every line cold. With criteria, you check each Then against the change, run the scenario if it is executable, and reject the merge request in minutes when a precondition was ignored.

It also catches scope creep early: any file touched that no scenario requires is drift, visible at a glance. We built Aerunit's story format around exactly this loop: criteria in, diff checked against criteria, agent redirected or merged.

When is a story too vague to hand to an agent at all?

Three warning signs. First, no testable outcome: if you cannot write a Given-When-Then that fails today and passes after the fix, the agent has nothing to verify against. Second, hidden product decisions: "make onboarding feel smoother" means you have not decided what the first-run flow should be, so the agent will decide for you. Third, criteria that require taste: "clean error handling" or "good performance" cannot be machine-checked, so the merge request review turns into an argument.

The fix is to decide first. Sit down, pick the behavior, write the acceptance criteria, then dispatch. If the decision genuinely needs human judgment across options, keep the story on a human's plate. An agent left to interpret intent is the chaotic intern problem, and no orchestrator fixes a story that was never specified.

How does story quality change the economics of an agent fleet?

At API prices, a team running up to thirty Claude Code and Codex sessions pays roughly $8 per merge request, with three humans supplying tasks and direction, as the Ticksly writeup covered earlier. In that setup, a vague story is the most expensive artifact in the pipeline: the agent wanders, burns the token budget on retries, and produces a diff a human must untangle.

The fix costs nothing. A story with one behavior and machine-checkable Given-When-Then criteria gets implemented once, and review becomes a checklist instead of a diff read cold. The classic template still anchors this: "As a [role], I want [feature], so that [benefit]" (Agile Alliance). The "so that" line is what keeps an agent from fixing the wrong thing for three hours. Cheaper stories, not cheaper models, are the lever you control.

What does a story template for parallel agents look like in practice?

Copy this into your task tracker and fill the brackets:

Intent: As [user], I want [behavior] so that [outcome].
Scope: repo [name], paths [globs]. Touch nothing else.
Criteria:
  Given [initial state]
  When [action]
  Then [machine-checkable result]
Out of scope: [refactors, other endpoints, schema changes].
Verify: [single command that exits 0 when criteria pass].

Five fields, each doing one job. The intent line sets direction, the scope boundary stops an agent from wandering into adjacent files, and the out-of-scope list pre-empts the "chaotic intern" fixes agents add unprompted. The verify command is the one reviewers trust: if it passes, the merge request matches the criteria; if it fails, you reject without reading the diff cold.

Paste the filled template as the agent's prompt, then paste it again as the reviewer's checklist. One behavior, one agent, one command to settle the argument.

FAQ

Can I write user stories in Gherkin directly, or do I need a separate acceptance criteria section?

Either works, as long as the Given-When-Then scenarios exist before you dispatch the agent. Many teams keep the "As a... I want... so that" line as a short intent header and put the scenarios directly beneath it. What matters is that the criteria are machine-checkable and present in the story text the agent actually reads.

How many acceptance criteria should one agent story have?

Enough scenarios to cover one behavior, usually two to four. Each scenario needs exactly one trigger and one checkable outcome, and anything joined by an "and" should be split into its own story. If you find yourself writing six or more scenarios, the story is too large for one agent and one merge request.

Do Gherkin stories replace tests, or do agents still write test code?

They do not replace tests. The Gherkin criteria define what done means; the agent still writes the test code that satisfies them. Because each Then names a concrete check, like a status code or an error message with exact text, the agent can run that check itself before opening the merge request, and the reviewer can rerun it in seconds.

What is the difference between a task and a user story for a coding agent?

A task is an instruction, like "add pagination to the invoices page." A user story for an agent adds three things the task lacks: a stated outcome explaining why, a scope boundary naming the files and repos it may touch, and machine-checkable acceptance criteria. The task tells the agent what to do; the story lets both agent and reviewer verify it was done.

How do I stop two parallel agents from working on the same story?

Put the ownership boundary in the story text itself, not in your head. Each story names its repos and paths explicitly, and sibling stories must not overlap. If two stories share a file, merge them or extract the shared change first. If story A's scenario requires touching a module story B owns, the split is wrong.

Aerunit

Halte die Agenten beschäftigt. Du übernimmst das Denken.

Die Registrierung ist offen — erstelle ein Konto und starte mit nutzungsbasierten Credits. Keine Abos, und Teams teilen sich ohne Aufpreis einen Credit-Pool.

Konto erstellen