Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

User Story

Pattern

A reusable solution you can apply to your work.

Understand This First

  • User – the “As a…” clause names a specific user type.
  • Problem – the “so that…” clause connects to the underlying problem.

Context

At the strategic level, a user story is a concise statement of desired user-centered behavior. It bridges the gap between product strategy and implementation by expressing a need from the User’s perspective in language the whole team (product, design, engineering, and AI agents) can act on.

User stories aren’t requirements documents. They’re invitations to a conversation about what the User needs and why. Their power comes from their brevity and their consistent focus on the person using the product, not on the technical implementation.

Problem

How do you translate a broad Problem statement or Roadmap goal into something a development team (or an AI agent) can build? Feature requests are often too vague (“improve search”), too prescriptive (“add a dropdown with these seven filter options”), or too disconnected from user intent (“refactor the search index”). The team needs a format that conveys who needs something, what they need, and why, without dictating the implementation.

Forces

  • Too much detail constrains the team and prevents creative solutions.
  • Too little detail leaves the team guessing about intent and acceptance criteria.
  • Technical language in requirements alienates non-technical stakeholders.
  • User-centered language keeps the focus on value rather than implementation.
  • Stories accumulate. Without discipline, a backlog becomes an unmanageable list of wishes.

Solution

Write user stories in the canonical format:

“As a [type of user], I want [some goal], so that [some reason].”

Each clause serves a purpose:

  • “As a…” names the specific User role. “As a new hire” is better than “as a user.”
  • “I want…” describes the capability or outcome, not the implementation.
  • “So that…” explains why this matters. This clause is the most important; it gives the team latitude to find the best solution and provides the basis for evaluating whether the solution actually works.

Supplement each story with acceptance criteria: concrete, testable conditions that define “done.” These criteria turn a conversational story into something verifiable.

For agentic workflows, user stories serve double duty: they communicate intent to human teammates and they can be used directly as prompts for AI agents. A well-written user story contains exactly the kind of context an AI agent needs to generate useful code.

How It Plays Out

A product manager writes: “As a team lead, I want to see which pull requests have been waiting more than 24 hours for review, so that I can follow up before they become blockers.” This story is clear enough for a developer to build and specific enough for an AI agent to generate a working prototype. The acceptance criteria might include: “The list updates in real time. PRs are sorted by wait time. The team lead can filter by repository.”

An engineering team uses AI agents to implement stories directly. The PM writes the story and acceptance criteria in a markdown file. The engineer pastes the story into the agent prompt along with relevant code context. The agent generates an implementation. The acceptance criteria become the basis for the test cases. The story format, originally designed for human communication, turns out to be an effective prompt structure for AI coding assistants.

Tip

When feeding user stories to an AI agent, include the “so that” clause. Without it, the agent optimizes for the literal feature request. With it, the agent can reason about edge cases: “The user wants to follow up on slow reviews. What if there are no slow reviews? What should the empty state look like?”

A common anti-pattern: writing stories that are actually technical tasks in disguise. “As a developer, I want to refactor the database layer, so that the code is cleaner” isn’t a user story; no end user benefits directly. It may be valid work, but it should be tracked as a technical task, not a story.

Example Prompt

“Implement this user story: As a team lead, I want to see which pull requests have been waiting more than 24 hours for review, so that I can follow up before they become blockers. The list should update in real time and sort by wait time.”

Consequences

User stories keep the team focused on delivering value to real people. They’re lightweight, easy to write, and easy to prioritize. They also make prioritization conversations more productive: “Which user need is more urgent?” is a better question than “which feature is more important?”

The limitation is that stories are intentionally incomplete. They’re starting points for conversation, not specifications. Teams that skip the conversation and treat stories as complete requirements end up building features that technically satisfy the story but miss the intent. The “conversation” part of stories, originally meant for humans, also applies when working with AI agents: refine the prompt, review the output, and iterate.

Stories also struggle to capture cross-cutting concerns like performance, security, and accessibility. These are better expressed as constraints that apply to all stories rather than as individual stories themselves.

  • Depends on: User — the “As a…” clause names a specific user type.
  • Depends on: Problem — the “so that…” clause connects to the underlying problem.
  • Refined by: Use Case — a use case expands a story into a detailed interaction description.
  • Uses: Roadmap — stories are the detailed expression of roadmap items.
  • Enables: Build-vs-Don’t-Build Judgment — evaluating a story’s value helps decide whether to build it.
  • Enables: Constraint — stories help define what is in scope and what is not.