Guide · Writing for agents

A good story isn't a long one

A coding agent can only run as well as the story you hand it. This guide is about transferring your intent — the mission, the boundaries, and what done means — not writing more words.

Mio Nilsson, creator of AerunitBy · Last updated

A glowing card sending a beam of light through a prism
The misconception

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]

The core move

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.

Where stories fail

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.

Definition of done

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]

Pointing, not describing

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.

Show, don't tell

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 we come in

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.

Quick answers

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]

Aerunit

Keep the agents busy. You do the thinking.

Sign-up is open — create an account and start with pay-as-you-go credits. No subscriptions, and teams share one credit pool at no extra cost.

Create account