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
What Is v0? Vercel's AI App Builder Explained
v0 is Vercel's AI app builder: describe a UI or an app and it generates a real Next.js project with React, Tailwind and shadcn/ui, with a live preview and one-click publishing to Vercel. What it's good at, how it differs from Lovable and Bolt, and what to know before shipping.
What Is UTF-8? Character Encoding and Garbled Text (Mojibake) Explained
UTF-8 is the character encoding that lets computers store every language and emoji as bytes — and it's the default almost everywhere now. How encoding works, why you see garbled text like ’ or é, and how to fix it in HTML, databases, CSV files and code.