User Story with Acceptance Criteria Examples: Weak vs Strong
9 min läsning
Key takeaways
- A user story states intent in one sentence; acceptance criteria are the binary-passable conditions that define done.
- Good criteria are binary-passable, observable from outside the system, and independent of implementation.
- Aim for 3-7 acceptance criteria per story so one agent session produces one merge request.
- Use checklist criteria for single observable facts and Given-When-Then for anything with branching or state.
- Acceptance criteria are per-story testable conditions; the definition of done is a team-level checklist enforced in CI.
A good user story with acceptance criteria examples shows the same story twice: a vague version an agent will misread, and a rewritten version with testable criteria it can implement without follow-up questions. This guide walks through those side-by-side rewrites for common SaaS features, then covers criteria written for machine implementers.
What does a user story with acceptance criteria look like?
A user story is one sentence in the "As a [role], I want [action], so that [outcome]" format, and its acceptance criteria are the testable conditions that must hold before the story is done. The story states intent; the criteria define the finish line. Mike Cohn's canonical writeup on the format and the INVEST criteria is still the best reference: user stories defined.
Annotated example:
As a tech lead, I want to see which of my parallel agents is blocked, so that I can unblock it before it burns tokens on the wrong thing.
Criteria:
- Each agent row shows a status of running, waiting, or failed.
- "Waiting" rows display the question the agent is waiting on.
- The list refreshes without a manual reload.
Vague criteria like "works well" fail because you cannot test them; "displays the question" passes or fails in one glance. We keep a full worked library of these at aerunit.ai/stories-for-coding-agents.
What makes an acceptance criteria example good or bad?
Run every criterion through three checks. It must be binary-passable, meaning an agent or a reviewer can say yes or no with no debate. It must be observable from outside the system, describing behavior a user sees, not code that was written. And it must be independent of implementation, so it survives a refactor or a swap from one framework to another.
Bad criterion: "The system should handle sync errors gracefully and efficiently."
It fails all three. "Gracefully" is not binary, nothing is observable, and "efficiently" hints at implementation. Fix it by naming the observable outcome: "When a sync fails, the merge request shows the error message from the API and the row stays in the queue for retry."
That rewrite gives a parallel agent something it can test before it reports done, and gives you something to check in seconds across a whole fleet. That split between describing the outcome and leaving the doing to the agent is the same discipline behind a good user story with acceptance criteria examples, and it is the one Mio Nilsson keeps coming back to.
How do you turn a vague user story into one with testable acceptance criteria?
Before: the vague version
As a user, I want to reset my password so that I can regain access to my account.
This gives an agent nothing to test. "Works" could mean anything: an email that never arrives, a reset link valid for a week, no rate limiting. An agent left with this story will pick the cheapest interpretation and ship it.
After: the rewritten story and criteria
As a registered user, I want to reset my password via email so that I can regain access without support involvement.
Acceptance criteria:
- Requesting a reset with a valid email sends a link within 60 seconds; the link expires after 30 minutes.
- Requesting a reset with an unknown email shows the same confirmation message (no account enumeration).
- A used or expired link returns an error and offers to restart the flow.
- A new password must be at least 12 characters; the user stays signed out until reset completes.
- More than 3 reset requests per email per hour are rejected.
What changed and why
Each criterion names a state, an error case, or a measurable limit, which is exactly what an agent needs to write its own failing tests first. The Given-When-Then structure in Gherkin syntax is the standard way to phrase these if you prefer that format. The same discipline applies when you distribute stories across a fleet: agents waiting on vague criteria idle or wander, and if you want to run more of them in parallel, request access to see how we keep them on target.
Which formats work for acceptance criteria: checklist vs Given-When-Then?
The same criterion in both formats:
Checklist: User is locked out after 5 failed logins in 15 minutes.
Given-When-Then: Given an account with 4 failed logins in the last 15 minutes, when a 5th login attempt with a wrong password fails, then the account is locked for 15 minutes and a lockout email is sent.
| Checklist | Given-When-Then | |
|---|---|---|
| Best for | Simple CRUD, UI states, constraints | Multi-step flows, branching, retries |
| Cost to write | Low | Higher |
| Failure modes it catches | Missing requirements | Logic gaps, edge cases |
| Agent-readability | Good | Better, if unambiguous |
The rule: use a checklist when the criterion is a single observable fact, and Given-When-Then when it hides a conditional or a sequence. A fleet of parallel agents benefits from Given-When-Then on anything with state, because "then" doubles as a test assertion. We compare both formats in the context of agent-implemented stories on our stories for coding agents page.
What do examples of user stories with acceptance criteria look like for real SaaS features?
Rewrite 1: seat-based team invitations
Weak: "As an admin, I want to invite my team so we can collaborate."
This fails because "collaborate" has no testable edge. Who can invite? What happens at the seat limit? The implementing agent will pick an answer, and you will not know which one until it ships.
Strong: "As a workspace admin, I want to invite teammates by email so that each invited user consumes one of the workspace's purchased seats." Acceptance criteria:
- Admin enters one or more email addresses; each address gets a single invitation.
- Inviting a user when all seats are used shows a seat-limit error and sends nothing.
- A pending invite can be revoked before acceptance, returning the seat to the pool.
- Invited users land in a "pending" state until they accept; they never see workspace data before accepting. The deltas: actor narrowed to admin, one seat-consumption rule per state change, and a defined failure path. Notice the criteria are written so an agent can verify each one from the diff and test run alone, the same discipline we break down in stories written for coding agents.
Rewrite 2: CSV export of usage data
Weak: "As a user, I want to export my usage data."
Strong: "As a workspace admin, I want to export the last 90 days of usage events as CSV so I can audit spend per member."
Acceptance criteria:
- Export covers exactly the selected date range, capped at 90 days.
- Columns are fixed and named: timestamp, member email, action, resource, tokens used.
- Exports larger than 10,000 rows are emailed as a download link rather than streamed.
- A member (non-admin) sees no export option.
The weak version hides three decisions: row cap, column schema, and permissioning. Each unnamed decision is a place where a parallel agent fleet drifts, duplicating work or overwriting a teammate's branch while you are reviewing another merge request. The Scrum community frames the same idea as shared, explicit agreement on what done means, per Scrum.org's Definition of Done guidance.
How many acceptance criteria should one user story have?
Aim for 3-7 acceptance criteria and scope the story so one agent session produces one merge request. That size fits your token budget and keeps a single agent from wandering.
Too few criteria (one or two) and the agent fills the gap with assumptions. It ships the happy path, skips validation, and you spend a review cycle describing what "done" should have meant.
Too many (ten-plus) and the story is really an epic. Agents working in parallel on a bloated story overwrite each other's work, and you lose the state tracking that makes a fleet manageable.
If a criterion feels minor, cut it. If a story needs eight criteria, split it into two stories.
How do acceptance criteria differ from a definition of done?
Acceptance criteria are the per-story conditions: specific, testable statements about one feature. A definition of done is the team-level checklist every story must pass before merging, regardless of content: tests written, code reviewed, docs updated, deployed. Scope, ownership, and examples differ:
- Acceptance criteria: written per story, owned by the story author, e.g. "expired sessions return 401."
- Definition of done: written once for the team, owned by the team, e.g. "all CI checks green."
The distinction matters more when agents do the work. Teams running large fleets report losing track of which agent is stuck on what, and the coordination cost grows with every session you add. Agents will happily claim done when only the criteria are met. Put the non-negotiables in the definition of done and enforce them in CI, so no merge request closes on a technicality.
How should acceptance criteria be written when a coding agent will implement the story?
Criteria as the agent's contract
A human developer reads a story and fills the gaps with judgment. An agent fills them with code, so every gap becomes a place it can wander. Write criteria as boundaries: name the files or directories in scope, name the behavior that must not change, and state the edge cases explicitly (empty input, concurrent edits, an id that does not exist). Take the CSV export story above.
A human implementer sees "capped at 90 days" and quietly decides whether that means 89, 90, or 91 days of events. An agent does the same, except it will not ask you at the standup; it commits its interpretation and moves on to the next criterion. Writing "exactly 90 days, inclusive of both endpoints" costs you ten seconds and removes an entire class of drift. "Splitting the thinking from the doing" applies here: the criteria are the thinking, fixed in advance, so the doing has rails.
Each criterion should also be independently verifiable by a test or a grep, because that is how the agent will check itself and how your retries will decide whether to re-run. Vague criteria produce the three-hours-fixing-the-wrong-thing session; testable ones produce a merge request you can accept or reject in one pass.
The review shortcut
The same list doubles as your review checklist: read the diff against the criteria, nothing else. With a fleet, that is the difference between supervising thirty sessions and reading thirty diffs cold.
Honest test against our own criteria: Aerunit orchestrates parallel agents with state tracking and task distribution, so criteria written this way feed directly into its per-agent instructions. What it does not do is write the criteria for you; the quality of the contract is still yours.
FAQ
Can acceptance criteria be written after development starts?
Yes, but the cost rises fast. Criteria written before work starts act as the contract the agent tests against; criteria written mid-session become a moving target the agent has already coded around. If you must add them later, pause the session, write the full list, and restart the agent with the updated story rather than patching incrementally.
Who writes acceptance criteria: the product owner, the developer, or the agent operator?
Whoever owns the story's intent, which for solo founders and small teams usually means you. The implementing agent should never author its own finish line, since it will pick the cheapest interpretation. Draft the criteria yourself, let the agent propose tests against them, and treat agent-suggested criteria as questions about scope, not decisions.
Do user stories need acceptance criteria for bugs and chores too?
Yes, in shortened form. A bug report without criteria invites the agent to fix symptoms: state the observable wrong behavior and the expected behavior, one line each. For chores like dependency upgrades, name the behavior that must not change and the checks that prove it. Both stay as checklists; Given-When-Then is rarely worth the overhead.
What is a good acceptance criteria template I can copy into Linear?
Per story, include: the story sentence (As a [role], I want [action], so that [outcome]); 3-7 checklist criteria, each binary-passable and observable from outside the system; a one-line out-of-scope note naming behavior that must not change; and edge cases such as empty input, missing id, or concurrent edit. Keep each item short enough to grep or test.