A user story is a concise description of a feature from the perspective of the person who wants it. Good user stories define what a system should do in terms the stakeholder cares about, without specifying how it should be implemented. In AI-assisted development, user stories have an additional role: they're the most direct context for a coding agent implementing a feature.
The user story format
The canonical format — "As a [user type], I want [goal] so that [reason]" — captures three essential elements: who benefits from the feature, what they want to do, and why. The "why" is often omitted in practice, but it's the most valuable part: understanding the reason behind a request allows implementers (human or AI) to make good tradeoff decisions when the exact how is ambiguous.
Example: "As a subscriber, I want to download my generated documents as a ZIP so that I can include them in my project repository without copying each file manually." The format makes the scope clear (a download feature), the user obvious (subscribers), and the context intelligible (it's for repository inclusion). A coding agent reading this story knows what to build and why.
The INVEST criteria
Good user stories satisfy the INVEST criteria:
- Independent — can be developed and delivered without depending on other unstarted stories
- Negotiable — the implementation details can be discussed; only the goal is fixed
- Valuable — delivers value to a specific user or stakeholder
- Estimable — the team can estimate the effort required
- Small — small enough to complete in one sprint or session
- Testable — there are clear, verifiable acceptance criteria
Stories that violate INVEST are either epics (too large — split them) or tasks (implementation details, not stories — remove the "as a user" framing). Both are useful artifacts; neither is a user story.
Writing acceptance criteria
Acceptance criteria define what "done" means for a story. They turn a qualitative goal ("users can download their documents") into verifiable conditions ("when the user clicks Download All, a ZIP file named project-name-documents.zip is downloaded containing all generated documents in PDF format"). Good acceptance criteria eliminate ambiguity about scope and make testing mechanical.
For AI coding agents, acceptance criteria are especially important: they define the exact target the agent is working toward. An agent with clear acceptance criteria can verify its own output; one without them has no way to know when it's finished. Write acceptance criteria before implementation, not after — they're the specification, not the test plan.
Common formats: Given/When/Then (behavior-driven), bullet list of verifiable conditions, or a table of input/output pairs for data-processing stories. The format matters less than the precision — each criterion must be unambiguously true or false.
User stories as AI agent context
When using AI coding agents, user stories serve as the primary task specification. Including the story — with acceptance criteria — at the start of an agent session gives the agent a complete, testable definition of what to build. The agent can reference the story to check its output against the acceptance criteria, flag ambiguities in the criteria, and stop when done rather than continuing past the defined scope.
The coordinate system in InitRepo's generated user stories tags each story with a phase and step coordinate (P#S#). This coordinate appears in the architecture spec and roadmap too — so an agent given a story coordinate can retrieve the corresponding architecture guidance and roadmap context without having to search for it. The coordinate is the retrieval key for cross-document context relevant to that story.
Organizing stories in a project
Stories belong to epics, which belong to phases. This hierarchy serves both planning and context: the epic defines the theme; the phase defines the sequence; the story defines the atomic deliverable. When presenting stories to an agent, include the epic context (one sentence describing the broader feature) alongside the story itself — it gives the agent the "why" for decisions the story doesn't specify.
Organize stories in priority order within each epic. Implement the foundational stories first; add enhancement stories after the core is working. This ordering should be explicit in the roadmap document — so the agent can sequence its implementation work correctly when given a phase to complete.
Common pitfalls
The most common user story mistakes: writing stories that are actually tasks ("refactor the auth module" has no user); writing stories too large to estimate or test in one session; omitting the "so that" clause, losing the rationale for later implementers; writing acceptance criteria so vague they're untestable ("the UI should be intuitive"); and writing stories from the developer's perspective rather than the user's.
For AI-assisted development, there's an additional pitfall: writing stories that assume an implementation approach. "As a user, I want the data stored in PostgreSQL" is not a story — it's a technical constraint. Keep stories at the goal level; put implementation constraints in the architecture document where they belong.