Good is not the same as long
When an agent comes back with something off target, the obvious reaction is to write more next time: more detail, more background, more prose. But length is a poor proxy for quality. A spec that rivals an RFC doesn't make an agent sharper — past a point, sheer size works against it, because "context window limits and the model's 'attention budget' get in the way." The better move is to break big tasks into smaller ones rather than pack everything into one giant prompt. [1]
The goal was never a longer ticket. It's removing the ambiguity that would otherwise surface as bad code and noisy review — as one vendor of agent tooling puts it. [2] A story is judged by one thing: does the agent come back having built what you meant? Everything else is decoration.
The reason this matters more now is that the reader changed. A user story has always been a conversation starter — a developer reads it, walks over to the person who wrote it, asks six questions, and fills the rest in from what they know about the codebase and the team. [3] An agent can't walk over to anyone. It reads what's on the page, fills every gap with its best guess, and builds exactly what it guessed. [3]
And when the story leaves room for interpretation, the agent will interpret — the fault is rarely the model, it's the contract it was handed. [4] The model is rarely the variable you control. The story is. [5]
Carry the vision, not just the task
The strongest story for an agent starts not with a to-do list but with a clear mission. State the goal and a few core requirements at a high level, and let the agent flesh out the details from there — models are good at elaborating on a solid directive, but they need a clear mission to avoid drifting off course. [1] Your job in the story is to transfer the vision; the agent's job is everything else.
This is why the classic user-story format has lasted: it packs three pieces of intent into one sentence — "as a [type of user], I want [some goal], so that [some reason]." The third clause, the part everyone skips, is the vision carrier:
"Without it, the agent optimizes for the literal feature request. With it, the agent can reason about edge cases." [6]
Watch what happens without it. "Fix the login bug" is a complete instruction to a human who was in the room when the bug was reported. To an agent it's a suggestion — it might return a 400-line pull request touching the password reset flow, the session middleware, and a feature flag, when the actual fix was a typo in an error message. [4] The vision in that story — who is locked out, what should happen instead, why it matters — is what would have picked the right implementation on the first try.
Close the gaps a human would close by asking
A human reader fills gaps with judgment, memory, and a cheap Slack message. An agent fills them with its defaults — and it will happily choose three attempts when you meant five, or lock accounts in a way that lets anyone lock out all of your customers. [3] The craft is naming the decisions where a wrong default would cost you. One simple test for each open decision: "Would I be annoyed if the agent guessed?" If yes, it belongs in the story. [7]
Out-of-scope matters as much as scope. A short "do not change" list — the behaviors, files, and boundaries the agent must leave alone — is often the single most useful sentence in the whole story, because without it the agent treats helpful cleanup as permission. [8] Explicit non-goals keep it from fixing things nobody asked it to fix. [9] Or, in one developer's words: "Five lines in the ticket prevent two hours in review." [4]
A story that carries this well reads like a small contract: the problem, the expected outcome, the acceptance criteria, the constraints, and what's off limits. Not because a template is magic — because each field is a gap that would otherwise be filled by a guess.
Start from done, not from the task
The highest-leverage habit is writing the acceptance checks first, and letting them pull the rest of the story into focus. [7] Acceptance criteria are observable behavior — what must be true after the change — not a restatement of the request. "The form submits" is a wish; "submitting with an expired token shows the session-expired screen and does not clear the drafted message" is a check.
The best checks are ones the agent can run itself: the command to run, the test that should pass, the failure cases to cover. Written once, they give you "acceptance criteria that define done for both the agent and the person" — "a single source of truth the agent builds from and the reviewer checks against." [10]
Define the handoff too. Ask the agent, in every story, to "summarize changed files, checks run, failures encountered, and any remaining risk" in its pull request. [9] It costs one line in the story and makes every review faster.
One more trick that keeps the vision honest: have the agent turn your intent into a first-draft spec, then fix the draft. If the agent's restatement of the story doesn't match what you meant, the gap is in your story — and it's far cheaper to find it before the pull request. [1]
Point at the code, not the idea
Agents don't need prose describing your architecture — they can read the code. What they can't infer is which parts of it this story touches. Point instead of describe: reference the files to touch, the existing patterns to mirror, the conventions to honor. [7] A five-line example in the story teaches the agent more than a paragraph explaining the rule.
And keep the work sized to one story — something that can be built and verified in a single afternoon — and split anything larger at the story level, before dispatch, not mid-run. [7] Smaller, sharper stories are also what make running several agents in parallel tractable — see our guide to parallel coding agents.
Example: before and after
Here's the same Linear issue, written twice.
Before
Fix login error messages
Users are confused by the login errors. Make them better.
After — example story (show)
Show a specific message when a login fails because the account is locked
Mission
As a customer who has been locked out, I want to see why I can't sign in, so that I reset my password instead of contacting support.
Acceptance checks
- A locked account shows "Your account is locked after 5 failed attempts" with a link to reset the password.
- Wrong password on an unlocked account still shows the generic "Email or password is incorrect".
- An email with no account gets the same lockout message after 5 failed attempts, so the message never reveals whether an account exists.
- Existing login tests pass; add one test for the locked case.
Non-goals
- Don't change the lockout threshold or duration.
- Don't touch the password reset flow or session middleware.
Look at
auth/login-form.tsx for the messages; mirror the error pattern in auth/signup-form.tsx.
Handoff
In the PR, summarize changed files, checks run, failures encountered and any remaining risk.
That last check is the "would I be annoyed if the agent guessed?" test in action: left unstated, a reasonable agent could easily show the lockout message only for real accounts — and leak which emails are registered.
Where Aerunit fits
Everything in this guide — the mission, the non-goals, the acceptance checks, the files to look at — is what Aerunit's story writer drafts for you. You describe the work; Aerunit reads your repositories and proposes Linear issues with scope, acceptance criteria and non-goals, pointing at the code that matters. You edit, approve, and the story is ready for an agent.
Aerunit reads every repository a story touches before writing it, so cross-repo work gets one coherent plan: a parent story plus one sub-issue per affected repo. And your team's conventions and reusable instructions are stored once as shared context and skills, then fed into every story and agent run — so you don't repeat "mirror the existing pattern" in every ticket, and agents don't reinvent your patterns.
Better stories
Scope, acceptance criteria and non-goals, drafted from your actual code.
Cross-repo plans
One parent story, one sub-issue per repository it touches.
Shared context
Team conventions written once, fed into every story and agent run.
Common questions
How long should a story for a coding agent be?
There's no target word count. Judge it by whether the agent could misread it, not by length: a story that states the outcome, the constraints, the acceptance checks and the non-goals can be short and still complete. Padding with background prose doesn't help — removing ambiguity does. [1]
Isn't this just writing a PRD?
No. A PRD is a document people align on; a story for an agent is a small executable contract — outcome, constraints, checks — sized to one run. The move is a clear mission plus the few decisions the agent shouldn't guess at. [1]
What if I'd rather just write a plain prompt?
For a small, well-understood task, fine. But the cost of a vague instruction grows with how many agents you run: the same under-specified prompt that costs one rework on a single agent becomes several wrong pull requests when you're running many in parallel — each built confidently against your vagueness.
Does a great story mean I can skip reviewing the work?
No — review is where you check the code against the vision only you hold. What a good story buys you is a faster review: the story states the outcome, and the agent's PR summarizes changed files, checks run, failures encountered and remaining risk, so the check is against a named target instead of a guess. [9]
Sources
- [1]Addy Osmani — How to write a good spec for AI agents
- [2]MergeLoom (vendor blog) — Ticket template for AI coding agents
- [3]Tensure — From user stories to specs: writing work for AI agents
- [4]tacoda on DEV Community — How to write a ticket an agent can act on
- [5]TaskFolk (vendor blog) — How to write a ticket an AI agent can actually finish
- [6]Encyclopedia of Agentic Coding Patterns — User story
- [7]Pooya Golchian — How to write specs for AI agents
- [8]Spec Coding — AI coding prompts that follow specs
- [9]Coding Agent Guide — Task briefs that produce reviewable changes
- [10]Atlassian — Spec-driven development in Jira
