User Stories

What Is a User Story and Why It Matters

Learn what user stories are, where they came from, and why they produce dramatically better results from AI coding tools.

What Is a User Story?

A user story is a short, simple description of a feature told from the perspective of the person who needs it — the user. User stories originated in Agile and Extreme Programming (XP) methodologies in the late 1990s as a reaction against heavyweight requirements documents that took weeks to write and were outdated by the time anyone read them.

The standard format is:

> As a [role], I want [goal], so that [benefit].

This three-part structure forces you to answer three essential questions before writing a single line of code: Who needs this? What do they want to do? Why does it matter to them?

User Stories vs Traditional Requirements

Traditional requirements documents are written by analysts who try to anticipate every edge case upfront. They produce long, formal documents filled with passive voice and ambiguous language ("The system shall provide the capability to..."). By the time development starts, requirements have often changed and the document is a fiction.

User stories take a radically different approach. They are:

  • Intentionally incomplete — they invite conversation rather than trying to capture everything
  • Written by anyone — product managers, developers, designers, even customers
  • Short enough to fit on a card — if it doesn't fit on an index card, it's too big
  • Validated through acceptance criteria — the conversation produces agreement on what "done" means

Why AI Coding Tools Need User Stories

When you use tools like Bolt.new, Claude Code, or Cursor, the quality of the output depends entirely on the quality of the input. Here is what happens with a vague prompt vs a user story:

Vague prompt: "Build me a todo app"

The AI fills every ambiguity with generic assumptions. You get a generic todo app that may not match what you wanted at all. You spend more time iterating than building.

User story with acceptance criteria: "As a developer, I want to add tasks to my list so that I can track what needs to be done. Given I am on the task list screen, when I type a task name and press Enter, then the task appears at the top of my list."

The AI now knows: who uses this (a developer), what they're doing (adding tasks), and exactly what behavior is expected (type + Enter → task appears at top). The first generated output is much closer to correct.

The story IS the prompt. A well-structured user story contains everything an AI needs to generate working code.

Three Worked Examples: Todo App

Story 1: Adding Tasks

*As a user, I want to add tasks to my list so that I can track what needs to be done.*

Acceptance Criteria:

  • Given I am viewing the task list, when I type text in the input field and press Enter, then a new task is added to the top of the list
  • Given I have typed a task, when I press Enter, then the input field clears automatically
  • Given the input field is empty, when I press Enter, then no task is added and the input remains focused

Story 2: Completing Tasks

*As a user, I want to mark tasks as complete so that I can see what I have already done.*

Acceptance Criteria:

  • Given I am viewing the task list, when I click the checkbox next to a task, then the task text shows a strikethrough style
  • Given a task is marked complete, when I click its checkbox again, then the task is marked incomplete and the strikethrough is removed
  • Given tasks are in the list, when I view the list, then complete tasks appear visually distinct from incomplete tasks

Story 3: Filtering by Status

*As a user, I want to filter tasks by status so that I can focus on what still needs to be done.*

Acceptance Criteria:

  • Given I am viewing the task list, when I click "Active", then only incomplete tasks are shown
  • Given I am viewing the task list, when I click "Completed", then only complete tasks are shown
  • Given I am viewing the task list, when I click "All", then all tasks are shown regardless of status

Key Takeaways

  • A user story follows the format: As a [role], I want [goal], so that [benefit]
  • User stories originated in Agile/XP as a lightweight alternative to requirements documents
  • Acceptance criteria in Given/When/Then format define exactly what "done" means
  • AI coding tools produce dramatically better output when given structured user stories
  • The story IS the prompt — a complete story contains everything AI needs to generate working code

Example

markdown
# User Story Format
As a [role],
I want [goal],
so that [benefit].

# Acceptance Criteria (Given/When/Then)
Given [precondition],
when [action],
then [expected result].

# Example
As a user,
I want to add tasks to my list,
so that I can track what needs to be done.

Given I type a task name and press Enter,
when the input is not empty,
then a new task appears at the top of the list.
Try it yourself — MARKDOWN