← Blog

10 tips for writing good user stories for coding agents

10 min de lecture

Key takeaways

  • Write acceptance criteria as machine-checkable conditions with numbers or commands, so an agent can tell finished from wandering.
  • Name the blast radius: list files and modules in scope and state explicit exclusions to keep parallel agents from overwriting each other.
  • Attach the why (issue links, user, workflow) and one worked input/output example, because an agent fills missing context with guesses instead of questions.
  • Keep the classic story shell but append a constraints block, and split large stories so one story equals one verifiable merge request sized for a single unattended session.
  • Store the ten rules as a skill or prompt template so every story gets the same structure, then review each PR against the story's criteria before merging.

These 10 tips for writing good user stories are evaluated through one filter: can a coding agent execute the story without wandering off? Each tip shows the classic agile meaning, the failure mode a parallel agent exhibits with the vague version, and the concrete rewrite that keeps it on target.

What makes a user story 'good' in agile — and does it change when an agent writes the code?

The classic definition still holds

A good user story is small, valuable to a user, and testable. The INVEST criteria — Independent, Negotiable, Valuable, Estimable, Small, Testable — have been the working standard since the early agile era, when teams started pushing back on heavyweight specs. Negotiable matters because a colleague who gets a vague story walks over and asks you.

What changes when the reader is an agent

An agent cannot ask. It executes whatever is written, including the ambiguity. When one person feeds a fleet of agents, the cost of a bad story compounds: the Ticksly team runs up to thirty Claude Code and Codex sessions at roughly $8 per merge request in API costs, and reports that "with that many terminal tabs you lose track fast" (dev1alone on Dev.to). Testable and Small matter most; Negotiable matters least. We collect the rewrites that make stories agent-executable in Stories for Coding Agents.

Why do vague acceptance criteria fail when handed to a coding agent?

A human teammate reads "make checkout faster" and asks a question. An agent reads it and starts shipping. Vague criteria are the root cause of both major failure modes in a parallel agent fleet.

Failure mode 1: the confident detour

Leave one AI coding agent alone for an hour and you get a chaotic intern: fast, eager, weirdly confident, and every so often completely wrong. With vague criteria, the agent has no way to tell "done" from "wandering," so it refactors code you didn't ask it to touch and burns your token budget doing it. The fix is the first of our 10 tips for writing good user stories: make every acceptance criterion machine-checkable. "Checkout completes in under 2s on the p95 benchmark" is verifiable; "faster checkout" is a guess.

Failure mode 2: two agents, one file

Run four agents without precise boundaries and they overwrite each other's work, duplicate each other, and argue in diffs. Machine-checkable criteria plus explicit scope ("only touch payments/") keep parallel agents in their lanes. We break down how orchestration layers like Aerunit track this state across a fleet.

Tip 1-3: Write the story so the agent can verify it finished

Tip 1: Acceptance criteria as checkable conditions

"Leave one AI coding agent alone for an hour and you get a chaotic intern," as one developer running four agents in parallel puts it. The fix is criteria the agent can test, not admire. Vague: "Improve checkout performance." Agent-executable: "Checkout POST responds under 300ms at p95 in the load test; add the test if missing; all existing tests pass."

Tip 2: Name the blast radius

Agents default to the smallest plausible change or wander into refactors you never asked for. Vague: "Fix the auth bug." Agent-executable: "Fix the token refresh in auth/session.ts; do not touch auth/oauth/ or the middleware signature." Naming files and modules in scope keeps a fleet of parallel agents from overwriting each other's work across repos.

Tip 3: Say what is out of scope

Explicit exclusions are cheap insurance. Vague: "Add CSV export to the orders page." Agent-executable: "Add CSV export for the orders list only. Out of scope: pagination changes, the invoice PDF path, any schema migration." Splitting the thinking from the doing is the whole trick; scope statements are how you do it in writing. For how orchestration tools compare on enforcing scope, see our comparison of cloud coding agents.

Tip 4-6: Give the agent context it cannot infer

A teammate reads a one-line story and fills the gaps from memory. An agent fills them with guesses, and those guesses become three hours of work on the wrong thing.

Tip 4: Link the why, not just the what

Attach the Linear issue, the bug report, or the design doc to every story. "Rate limit login attempts" tells the agent nothing about why; linking the issue that documents five brute-force attempts last week tells it the threat model. If the why changes scope, the agent needs that context to make the call itself instead of waiting on an approval prompt.

Tip 5: Name the user and the workflow

State who runs the workflow and what happens before and after the story. "As the ops lead reconciling nightly Stripe payouts, I need X so the morning report matches the ledger" pins the story to a real sequence. Without it, an agent optimizing for the happy path will happily break the retry logic nobody mentioned. The same discipline applies when you compare orchestration setups in cloud coding agents compared: context quality, not model choice, is what keeps a fleet on target.

Tip 6: Show one worked example

Include expected input and output in the story itself. "Given a payload of 10,000 rows with 3 duplicates, the endpoint returns 9,997 rows and a 200" is a test the agent can verify before it claims done. One concrete example beats a paragraph of adjectives, and it doubles as your acceptance check when the merge request lands.

How should you structure a user story so an AI agent stays on target?

Tip 7: Keep the classic shell, add a constraints block

The "as a X I want Y so that Z" shell still earns its place: it forces you to state the actor, the capability, and the reason, which is the minimum an agent needs to judge scope. What the shell omits is everything the agent will otherwise guess at: which repos it may touch, which files are off-limits, which patterns to follow, what counts as done.

So append a constraints block under the shell:

Before: "As a user, I want faster search so that I can find tickets quickly."

After: "As a support lead, I want ticket search to filter by status and assignee so that I can triage without opening each ticket. Constraints: only search/ module; reuse the existing query builder; no new dependencies; all acceptance criteria in the checklist must pass before you open the merge request."

Tip 8: Split the thinking from the doing

The story is the thinking; the run is the doing. Write the plan, scope, and acceptance criteria while you are away from the terminal, then hand the agent a narrow execution task. As one practitioner put it, "Splitting the thinking from the doing is the whole trick" (dev.to).

Before: "Fix the flaky checkout tests."

After: "Run checkout suite in the payments repo. If a test fails, diagnose against the acceptance criteria below; do not modify test fixtures. Report the failing assertion before retrying."

This matters more as fleets grow: when you coordinate many parallel agents, the bottleneck is often the model's own multi-step judgment, not the orchestrator. Tools like Aerunit exist to keep runs on target, but a tight story is the cheapest steering you will ever do.

How do you split a large user story into agent-sized pieces?

Tip 9: One story, one verifiable merge request

In classic agile, splitting by outcome means each story ships something a user could touch. For an agent, that translates directly: one story, one merge request, one set of acceptance criteria that a reviewer can approve or reject on its own. If two stories land in the same MR, you cannot verify either one finished, and a second agent touching the same branch risks overwriting the first one's work.

Split along the seams a human reviewer would check:

Split byBad storyAgent-sized story
Data model"Add saved searches""Add saved_searches table and migration"
Endpoint"Add saved searches""Expose POST /saved-searches, tests included"
UI"Add saved searches""Render saved-search list from existing endpoint"

Each row is independently verifiable and reviewable as its own MR.

Tip 10: Size for a single unattended session

Before starting a run, ask: can one agent finish this without stopping to ask a human anything? If the story depends on a decision mid-run, like choosing between two auth approaches, that decision belongs in the story as acceptance criteria, not in the agent's queue of approval prompts. A story that fits a single session keeps your token budget predictable and your fleet moving; one that stalls mid-run leaves an agent idle for hours while the rest of the swarm waits.

Which tools help you write and validate user stories before a run?

Where stories live vs where runs happen

A classic story is a placeholder for a conversation between people (Mike Cohn's definition and the INVEST acronym). An agent story is a contract a daemon can verify. That split defines your stack: Linear is where stories live and get triaged; Cursor Cloud Agents and GitHub Copilot coding agent are where runs execute; Vibe Kanban gives you a board for parallel agents across repos; Aerunit sits over the fleet, tracking each run against the story's acceptance criteria so a stalled or wandering agent is visible before it burns an hour.

Running the tools through the same criteria

Judge each on three questions. Can it hold the acceptance criteria verbatim? Can it show per-run state — waiting, off-target, done? Does it catch an agent overwriting another's work?

Linear stores stories well but tracks no runs. Cursor and Copilot execute but scope to their own runs. Vibe Kanban and Aerunit both handle parallel agents; Aerunit's edge is continuous verification against the story itself, though it assumes your stories are already agent-executable — which is what the other tips fix.

What role does a Claude skill or prompt template play in consistent story writing?

Ten tips only work if they get applied every time, including when you're writing stories at 11pm before queuing up the fleet. A stored skill or prompt template turns the checklist into the default: story format, context blocks, acceptance criteria as verifiable assertions, split rules. The template remembers the structure so you don't have to.

A skill as a story-writing checklist

Write the skill once, with the ten rules as explicit requirements: every story must name the repo, the files in scope, the token budget, and the acceptance criteria as testable statements. Then every story your team drafts comes out with the same shape, whether you wrote it or a teammate did. Consistent structure also means your agents start from the same expectations every run, which cuts the wandering-off problem.

Reviewing the PR against the story

Before merging, diff the PR against the original story: does each acceptance criterion map to a test or a demonstrable change? Run this check per agent when several are in flight, because one bad merge request among thirty is easy to miss. Reject against the criteria, not the vibe.

FAQ

How long should a user story be for a coding agent?

Long enough to remove every guess, short enough to fit one unattended session. A one-liner plus a constraints block usually works: actor, capability, reason, then files in scope, exclusions, and acceptance criteria. If the story needs a mid-run human decision, it is too big or too vague; split it until a single session can finish without asking.

Can I write user stories with Claude or another LLM?

Yes, and it works best when you give the model the checklist: name the repo, list files in scope, state exclusions, and require acceptance criteria as testable statements. A stored skill or prompt template enforces that structure every time, so stories drafted at 11pm come out the same shape as ones you write carefully. Always review the draft against the criteria before queuing a run.

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

A story is the thinking: the why, the scope, the acceptance criteria, the worked example. A task is the doing: a narrow execution run an agent can complete in one session. Classic agile treats a story as a placeholder for a conversation; an agent story is a contract a daemon can verify, and tasks are the individual runs checked against that contract.

How do I write acceptance criteria that an agent can test automatically?

Write each criterion as a checkable condition with a number or a command: "Checkout POST responds under 300ms at p95 in the load test; add the test if missing; all existing tests pass." Include one worked input and output the agent can verify before claiming done. Avoid adjectives like "faster" or "better"; they give the agent no way to tell finished from wandering.

Aerunit

Occupez les agents. Gardez la réflexion.

Les inscriptions sont ouvertes — créez un compte et commencez avec des crédits à l'usage. Aucun abonnement, et les équipes partagent une réserve de crédits sans surcoût.

Créer un compte