user-stories

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When this skill is activated, always start your first response with the 🧢 emoji.

激活此技能后，首次回复请务必以🧢表情开头。

User Stories

用户故事

User stories are short, plain-language descriptions of a feature from the perspective of the person who wants it. They are the primary unit of work in agile teams - a shared, human-readable contract between product, design, and engineering that keeps teams focused on user value rather than technical implementation details.

用户故事是从需求方视角出发，用简洁平实语言描述功能的短文本。它们是敏捷团队的主要工作单元——是产品、设计与开发团队之间一份共享的、通俗易懂的约定，确保团队始终聚焦用户价值而非技术实现细节。

When to use this skill

何时使用此技能

Trigger this skill when the user:

Wants to write or improve a user story
Needs to define acceptance criteria for a feature
Is creating or facilitating a story mapping session
Wants to groom or refine a product backlog
Needs to estimate stories with story points or t-shirt sizes
Asks about INVEST criteria or whether a story is well-formed
Needs to split a large story or epic into smaller deliverable stories
Wants to write technical stories, spikes, or enabler stories

Do NOT trigger this skill for:

Sprint planning ceremonies (scheduling and capacity work, not story writing)
Project roadmaps and OKRs (strategy-level, above story granularity)

当用户有以下需求时触发此技能：

想要编写或优化用户故事
需要为功能定义验收标准
正在创建或主持故事地图绘制会议
想要梳理或优化产品待办事项
需要用故事点数或T恤尺码法估算用户故事
询问INVEST准则或某个故事是否符合规范
需要将大型故事或史诗拆分为可交付的小型故事
想要编写技术故事、探索型任务（Spike）或赋能型故事

请勿在以下场景触发此技能：

冲刺规划会议（涉及日程安排与容量规划，而非故事编写）
项目路线图与OKR（战略层面，粒度高于用户故事）

Key principles

核心原则

INVEST criteria - Every story should be Independent, Negotiable, Valuable, Estimable, Small, and Testable. A story that fails any criterion needs rework before it enters a sprint. See the Core Concepts section for the full breakdown.
Acceptance criteria are testable - Acceptance criteria must be written so that a tester (human or automated) can unambiguously determine pass or fail. Vague criteria like "the UI should look good" are not acceptance criteria - they are opinions. Rewrite them as concrete, observable outcomes.
Vertical slices, not horizontal - A story must deliver end-to-end value: a real user doing a real thing and getting a real result. A story that covers only the database layer, only the API, or only the UI is a task, not a story. Horizontal slicing creates work that sits unfinished for sprints; vertical slicing enables continuous delivery.
Conversation over documentation - The written story is a placeholder for a conversation, not a complete specification. The three C's (Card, Conversation, Confirmation) mean the card captures the intent, the team talks through details during grooming and planning, and acceptance criteria confirm shared understanding. Resist writing exhaustive specifications - keep the card short and talk.
Stories are negotiable - The "N" in INVEST. A story is not a contract. The team and product owner negotiate scope, approach, and details right up until the sprint begins. If a story cannot be adjusted, it is a requirement document masquerading as a story.

INVEST准则 - 每个故事都应满足独立（Independent）、可协商（Negotiable）、有价值（Valuable）、可估算（Estimable）、小型（Small）、可测试（Testable）。任何不满足其中一项的故事，在进入冲刺前都需要返工。详见核心概念部分的完整说明。
验收标准需可测试 - 验收标准的编写必须让测试人员（人工或自动化）能明确判断通过或失败。像“UI看起来要美观”这类模糊描述不属于验收标准——它们是主观意见。应将其改写为具体、可观察的结果。
垂直切片而非水平切片 - 故事必须交付端到端价值：真实用户完成真实操作并获得真实结果。仅覆盖数据库层、仅覆盖API或仅覆盖UI的内容是任务，而非故事。水平切片会导致工作在多个冲刺中处于未完成状态；垂直切片则支持持续交付。
对话优先于文档 - 书面故事只是对话的占位符，而非完整的规范。三个C原则（Card卡片、Conversation对话、Confirmation确认）意味着卡片记录核心意图，团队在梳理与规划过程中讨论细节，验收标准确认共识。避免编写详尽的规范——保持卡片简洁，多沟通。
故事是可协商的 - 即INVEST中的“N”。故事不是合同。团队与产品负责人可在冲刺开始前随时协商范围、实现方式与细节。如果某个故事无法调整，那它只是伪装成故事的需求文档。

Core concepts

核心概念

Story anatomy

故事结构

The standard template - "As a [persona], I want [action], so that [outcome]" - has three parts, each carrying weight:

Persona (
```
As a...
```
) - Who benefits? Use a real persona or role, not "user" or "system." The persona grounds every decision in a real person's need.
Action (
```
I want...
```
) - What do they want to do? This is the feature, stated as a user action, not a system capability.
Outcome (
```
So that...
```
) - Why do they want it? The business or user value. This is the most important part - it prevents teams from building the wrong thing correctly.

标准模板——“作为[具体角色]，我想要[具体操作]，以便[可衡量的结果]”——包含三个部分，各有其重要性：

角色（
As a...
） - 谁能从中受益？使用真实角色或身份，而非“用户”或“系统”。明确的角色能让所有决策基于真实用户的需求。
操作（
I want...
） - 他们想要做什么？这是功能的描述，需以用户动作而非系统能力的方式表述。
结果（
So that...
） - 他们为什么需要这个功能？关联用户或业务价值。这是最重要的部分——防止团队正确地构建了错误的功能。

INVEST criteria

INVEST准则

Letter	Criterion	What it means
I	Independent	Can be developed and delivered without depending on another story
N	Negotiable	Scope and details can be adjusted before the sprint
V	Valuable	Delivers perceivable value to a user or the business
E	Estimable	The team can size it; if not, it needs splitting or a spike
S	Small	Fits in one sprint; ideally completable in 2-3 days
T	Testable	Acceptance criteria exist and can be verified

字母	准则	含义
I	Independent（独立）	可独立开发与交付，无需依赖其他故事
N	Negotiable（可协商）	冲刺前可调整范围与细节
V	Valuable（有价值）	为用户或业务带来可感知的价值
E	Estimable（可估算）	团队可评估其规模；若不能，则需拆分或创建探索型任务
S	Small（小型）	可在一个冲刺内完成；理想情况下2-3天可交付
T	Testable（可测试）	存在验收标准且可验证

Acceptance criteria formats

验收标准格式

Given/When/Then (Gherkin) is the most structured format and maps directly to automated tests:

Given [initial context / precondition]
When  [action or event]
Then  [expected outcome]

Checklist format works for stories with multiple independent outcomes:

- [ ] User can sort the table by any column
- [ ] Sort order persists across page refreshes
- [ ] Default sort is by date descending

Use Gherkin for behavior-critical paths (auth, payments, core flows). Use checklists for UI stories with many small, independent criteria.

**Given/When/Then（Gherkin）**是结构最清晰的格式，可直接映射到自动化测试：

Given [初始上下文/前置条件]
When  [动作或事件]
Then  [预期结果]

清单格式适用于包含多个独立结果的故事：

- [ ] 用户可按任意列对表格排序
- [ ] 排序顺序在页面刷新后仍保留
- [ ] 默认按日期降序排序

对于行为关键路径（认证、支付、核心流程）使用Gherkin格式。对于包含多个小型独立准则的UI故事使用清单格式。

Story mapping

故事地图（Story mapping）

Story mapping organizes stories into a two-dimensional grid:

Horizontal axis (Backbone) - User activities in the order a user experiences them (left to right). These are big-bucket steps like "Browse catalog," "Add to cart," "Checkout," "Receive order."
Vertical axis (Depth) - Stories under each activity, ordered by priority (top = must-have, bottom = nice-to-have).
Horizontal slices - Drawing a line across all activities at the same depth creates a release slice that delivers a complete, thin version of the product.

故事地图将用户故事组织成二维网格：

水平轴（主干） - 用户体验流程中的各项活动（从左到右）。这些是大的分类步骤，如“浏览商品目录”、“加入购物车”、“结账”、“接收订单”。
垂直轴（深度） - 每个活动下的故事，按优先级排序（顶部=必备功能，底部=锦上添花功能）。
水平切片 - 在所有活动的同一深度画一条线，形成一个发布切片，可交付产品的完整精简版本。

Common tasks

常见任务

Write effective user stories

编写高效的用户故事

Template:

As a [specific persona],
I want [specific action],
So that [measurable outcome].

Weak story (before):

As a user, I want to search, so that I can find things.

Strong story (after):

As a returning customer,
I want to search my order history by product name or order date,
So that I can quickly find and re-order items I've bought before.

The strong version names the persona, specifies the exact action, and ties the outcome to a real business motivation (re-orders).

Checklist before writing:

Is the persona specific enough to guide design decisions?
Is the action a user action, not a system behavior?
Does the "so that" capture user or business value - not technical rationale?
Can this be delivered in a single sprint?

模板：

作为[具体角色]，
我想要[具体操作]，
以便[可衡量的结果]。

薄弱的故事（优化前）：

作为用户，我想要搜索功能，以便找到内容。

优质的故事（优化后）：

作为回头客，
我想要按商品名称或订单日期搜索我的订单历史，
以便快速找到并重新订购我之前购买过的商品。

优化后的版本明确了角色，指定了具体操作，并将结果与真实的业务动机（复购）关联起来。

编写前检查清单：

角色是否足够具体，能指导设计决策？
操作是否是用户动作，而非系统行为？
“以便”部分是否捕捉到用户或业务价值——而非技术理由？
能否在单个冲刺内交付？

Write acceptance criteria - GWT format

编写验收标准 - GWT格式

Write one scenario per distinct behavior. Cover the happy path first, then edge cases and error states.

Story: As a shopper, I want to apply a discount code at checkout, so that I receive the discount on my order total.

gherkin

Scenario: Valid discount code applied
Given the shopper has items in their cart totaling $80
When they enter a valid 20%-off code "SAVE20" at checkout
Then the order total shows $64.00
And the applied discount is itemized on the order summary

Scenario: Expired discount code
Given a discount code "SUMMER22" that expired on 2022-09-01
When the shopper enters "SUMMER22" at checkout
Then an error message reads "This code has expired"
And the order total is unchanged

Scenario: Code already used (single-use code)
Given the shopper has already used single-use code "WELCOME10"
When they enter "WELCOME10" again at checkout
Then an error message reads "This code has already been used"

每个独特的行为对应一个场景。先覆盖正常路径，再处理边缘情况与错误状态。

故事： 作为购物者，我想要在结账时使用折扣码，以便享受订单总价折扣。

gherkin

Scenario: Valid discount code applied
Given the shopper has items in their cart totaling $80
When they enter a valid 20%-off code "SAVE20" at checkout
Then the order total shows $64.00
And the applied discount is itemized on the order summary

Scenario: Expired discount code
Given a discount code "SUMMER22" that expired on 2022-09-01
When the shopper enters "SUMMER22" at checkout
Then an error message reads "This code has expired"
And the order total is unchanged

Scenario: Code already used (single-use code)
Given the shopper has already used single-use code "WELCOME10"
When they enter "WELCOME10" again at checkout
Then an error message reads "This code has already been used"

Create a story map - step by step

创建故事地图 - 分步指南

Define the user - Agree on which user (persona) the map is for. One map per primary user type.
List user activities - Brainstorm the big steps the user takes (post-its, one per card). Arrange left to right in user journey order. Aim for 5-10 activities.
Break activities into tasks - Under each activity, list the user tasks (specific actions). These become the backbone of your stories.
Write stories under tasks - Under each task, write the stories needed to support it. Stack them vertically with highest priority on top.
Draw release slices - Draw horizontal lines through the map. Everything above the first line = MVP. Everything above the second line = v1.1. Etc.
Validate the slices - Each slice should be a coherent, releasable product. Ask: "Could a user get value from only what's above this line?"

定义用户 - 确定地图针对的用户（角色）。每个主要用户类型对应一个地图。
列出用户活动 - 头脑风暴用户执行的主要步骤（用便利贴，每个步骤一张）。按用户旅程顺序从左到右排列。目标是5-10个活动。
将活动拆分为任务 - 在每个活动下，列出用户任务（具体动作）。这些将成为故事的主干。
在任务下编写故事 - 在每个任务下，编写支持该任务所需的故事。按优先级从上到下堆叠。
绘制发布切片 - 在地图上绘制水平线。第一条线上方的所有内容=最小可行产品（MVP）。第二条线上方的所有内容=v1.1版本，以此类推。
验证切片 - 每个切片都应是一个连贯的、可发布的产品。自问：“用户仅使用线上方的功能能否获得价值？”

Groom and refine backlog

梳理与优化待办事项

Run a grooming session against each story using this checklist:

Clear? Can the team explain it back in their own words?
INVEST? Does it pass all six criteria?
Acceptance criteria complete? At least one happy-path scenario, one error case.
Dependencies identified? Are blockers noted and tracked?
Ready to estimate? If the team cannot size it, create a spike story.
Definition of Done applicable? Does standard DoD cover this, or are there story-specific done criteria?

If a story fails more than two items, send it back to the product owner for rework rather than attempting to fix it in the grooming meeting.

针对每个故事，使用以下清单开展梳理会议：

清晰易懂？ 团队能否用自己的语言复述故事内容？
符合INVEST准则？ 是否满足全部六项准则？
验收标准完整？ 至少包含一个正常路径场景和一个错误场景。
已识别依赖关系？ 是否已记录并跟踪阻塞因素？
准备好估算？ 如果团队无法评估规模，创建一个探索型任务（Spike）。
适用完成定义（DoD）？ 标准DoD是否覆盖此故事，还是需要特定的完成标准？

如果一个故事不满足超过两项检查项，应将其退回给产品负责人返工，而非在梳理会议中尝试修复。

Estimate with story points - relative sizing

用故事点数估算 - 相对规模

Story points measure complexity + uncertainty + effort relative to a reference story, not time.

Step-by-step with planning poker:

Select a reference story the whole team agrees is "a 3." Post it visibly.
Read the new story aloud. Give everyone a moment to think silently.
All team members reveal their estimate simultaneously (cards or app).
If estimates converge (within one Fibonacci step): accept the majority or average.
If estimates diverge: the highest and lowest estimators explain their reasoning. Discuss until convergence, then re-estimate once.

Fibonacci scale: 1, 2, 3, 5, 8, 13, 21, ? (unknown), infinity (too large)

Sizing heuristics:

Points	Meaning
1-2	Well-understood, trivial change, clear path
3-5	Moderate work, minor unknowns, typical story
8	Complex, significant unknowns - consider splitting
13+	Too large for one sprint. Must split before committing
?	Team doesn't understand the story - needs a spike

故事点数衡量的是复杂度+不确定性+工作量，以某个参考故事为基准，而非时间。

规划扑克分步流程：

选择一个团队一致认为是“3点”的参考故事，将其显眼地展示出来。
大声朗读新故事。给所有人一点时间独立思考。
所有团队成员同时亮出自己的估算结果（使用卡片或应用程序）。
如果估算结果趋同（在斐波那契数列的一个步长内）：接受多数结果或平均值。
如果估算结果分歧较大：估算值最高和最低的成员解释其理由。讨论直至达成共识，然后重新估算一次。

斐波那契量表： 1, 2, 3, 5, 8, 13, 21, ?（未知）, 无穷大（过大）

规模估算启发式：

点数	含义
1-2	理解充分，改动微小，路径清晰
3-5	工作量适中，存在少量未知，典型故事
8	复杂度高，存在显著未知——考虑拆分
13+	过大，无法在一个冲刺内完成。提交前必须拆分
?	团队不理解故事内容——需要创建探索型任务

Split large stories - patterns

拆分大型故事 - 模式

See

references/story-splitting.md

for the full 10-pattern reference.

Quick reference - top 3 patterns:

By workflow step - Break the story at each step in the user's process. "As a user, I want to complete checkout" splits into: enter shipping address / enter payment / review and confirm / receive confirmation email.
By data variation - If a story handles many types of input, start with the simplest type and add variations in follow-on stories. "Search by name" / "search by date" / "search by category."
Happy path first - Implement the success case, defer error handling and edge cases to a follow-on story. Always ship the happy path first.

查看

references/story-splitting.md

获取完整的10种拆分模式，每种模式都配有实例。当故事过大或史诗需要拆分时加载此文档。

快速参考 - 前3种模式：

按工作流步骤拆分 - 在用户流程的每个步骤处拆分故事。例如“作为用户，我想要完成结账”可拆分为：输入收货地址/输入支付信息/确认订单/接收确认邮件。
按数据变体拆分 - 如果故事处理多种输入类型，从最简单的类型开始，后续故事添加变体。例如“按名称搜索”/“按日期搜索”/“按分类搜索”。
先实现正常路径 - 先实现成功场景，将错误处理和边缘情况推迟到后续故事。始终优先交付正常路径。

Write technical stories and spikes

编写技术故事与探索型任务（Spike）

Technical story template:

In order to [technical goal / business benefit],
As [team or role],
We need to [technical action].

Example:

In order to meet the 200ms API response SLA,
As the platform team,
We need to add a Redis cache layer in front of the product catalog endpoint.

Spike template (time-boxed research):

Spike: [question to answer]
Timebox: [hours]
Output: [what the team will have at the end - a decision, a prototype, an ADR]