User Stories Explained: Format, Examples and Acceptance Criteria
A user story describes a feature from the user's point of view: As a [user], I want [action], so that [benefit]. How to write good ones, acceptance criteria with Given/When/Then, splitting big stories, common mistakes, and why stories make better prompts for AI coding tools.
A user story is a short description of something a user wants to do, written from their point of view. It's the basic building block for planning software in small pieces.
The format
As a [type of user], I want [to do something], so that [I get some benefit].
Examples:
As a shopper, I want to save items to a wishlist, so that I can buy them later.
As a team admin, I want to remove a member, so that former employees lose access.
As a freelancer, I want to see which invoices are overdue, so that I know whom to chase.
The "so that" is the most important part. It explains why, which helps you (or an AI tool) choose the right solution and spot when a simpler one would do.
Acceptance criteria: when is it done?
A story alone is vague. Acceptance criteria are the specific conditions that must be true for it to count as finished.
A popular format is Given / When / Then:
Story: As a shopper, I want to save items to a wishlist, so that I can buy them later.
- Given I'm logged in, when I click the heart on a product, then it's added to my wishlist.
- Given an item is in my wishlist, when I click the heart again, then it's removed.
- Given I'm not logged in, when I click the heart, then I'm asked to log in, and the item is saved after I do.
- Given an item in my wishlist goes out of stock, then it's shown as unavailable.
Criteria cover the edge cases — logged out, duplicates, missing data — where bugs live. They also translate directly into tests. (How to test your app before launch)
What makes a good story
A common checklist is INVEST:
- Independent — can be built without waiting on another story.
- Negotiable — describes the need, not a fixed design.
- Valuable — a user (not just a developer) gets something.
- Estimable — clear enough to judge its size.
- Small — fits in a few days, ideally less.
- Testable — you can check it's done.
Splitting big stories
"As a user, I want to manage my account" is too big — it's an epic. Split it:
- change my email
- change my password
- turn on two-factor authentication
- delete my account
Split by step in a workflow, by type of user, by happy path vs edge cases, or "simple version first, extras later". Each piece should still be useful on its own. (What is an MVP?)
Common mistakes
- Technical tasks dressed as stories. "As a developer, I want a database index" isn't a user story. That's fine as a task — just don't pretend it's user value.
- No "so that". Without the why, you can't judge solutions.
- The solution in the story. "I want a dropdown" — maybe they need search instead.
- Criteria that can't be checked. "Fast", "easy", "intuitive". Say what fast means.
User stories as AI prompts
User stories with acceptance criteria are excellent input for AI coding tools. Compare:
add a wishlist
with:
Implement this story. As a shopper, I want to save items to a wishlist so I can buy them later. Acceptance criteria: [the four above]. Write tests for each criterion, then implement until they pass.
The second gives the agent the goal, the edge cases, and a way to check its own work. (How to write good prompts for AI coding tools, Getting AI to write tests that catch bugs)
Where stories live
A Markdown file in your repo, GitHub Issues, Linear, Trello — anything. What matters is keeping them small, ordered by importance, and updated. (How to write a PRD)
EasySpawn gives Claude Code a persistent workspace with your stories, code and running app together — hand it a story with acceptance criteria and check the live result. See how it works or join the waitlist.
Related: How to Write a PRD · How to Plan Your First App · Spec-Driven Development · What Is an MVP?
Keep reading
How to Write a Product Requirements Document (PRD) — With AI's Help
A PRD says what you're building, for whom, and how you'll know it works — before anyone writes code. What goes in a good one, a short template, how to use AI to draft and pressure-test it, and why a clear PRD is the best input you can give an AI coding tool.
Why Does AI Hallucinate? And How to Reduce It in Your App
AI models sometimes state false things with complete confidence. Why it happens — they predict plausible text rather than look up facts — the kinds of hallucination you'll meet in coding and apps, and practical ways to reduce it: grounding, tools, structure, checks and room to say 'I don't know'.