Keeping Stories Small
The most common mistake is a story that’s too big. If describing a story takes more than a short paragraph, it’s probably two stories.
Signs a story is too large
Section titled “Signs a story is too large”- It touches more than one page or section of the app.
- It needs new components, new API calls and new validation logic all at once.
- You find it hard to describe a single, clear success condition.
- Building it would mean several independent decisions that could each go a different way.
When in doubt, split it
Section titled “When in doubt, split it”Claude builds and tests each story as its own unit, then commits it. Small stories keep each unit focused, so the result stays close to what you had in mind. Large, ambiguous stories take longer, need more fix cycles, and drift from your intent.
Small stories also make the manual test easier: each one has a short checklist you can check quickly. Claude warns you if an epic’s manual test grows past about 30 items, because that usually means the epic should have been split.
You can split a story on the stories review page before you approve it. The Split button turns one story into two that you can trim separately.
Examples
Section titled “Examples”| Good story size | Too large |
|---|---|
| ”A user can filter the product list by category" | "Build the checkout flow” (an epic, not a story) |
| “Show a loading spinner while the product list is fetching" | "The product page should work properly” (a goal, not a story) |
| “A user can see their past orders in a list, newest first" | "Add a dashboard” (needs breaking into individual stories) |