user-story

目的

创建清晰、简洁的用户故事，将 Mike Cohn 的用户故事格式与 Gherkin 风格的验收标准结合起来。借此将用户需求转化为可执行的开发工作，聚焦于成果，确保产品与工程团队达成共识，并提供可测试的成功标准。

这不是功能规格说明，而是一个讨论的起点，用来记录谁会受益、他们想做什么、为什么这很重要，以及如何判断它是否奏效。

输入

最适合： 故事所涵盖的功能或用户需求。 也有帮助： 用户角色、他们想要的结果，以及验收标准必须涵盖的边缘情况。

在调用时一并提供的任何内容——技能名称之后的文本、粘贴的上下文信息，或附加的 ARGUMENTS: 行——都算作已提供的答案。使用这些内容，并跳过其中已经涵盖的问题；不要重复询问。

什么都没准备也没关系。 该技能会先询问用户是谁，以及他们想要完成什么，然后再起草故事和 Gherkin 标准。

调用示例： 为我们的银行应用编写有关通过短信重置密码的用户故事，并涵盖账户锁定的边缘情况。

核心概念

Mike Cohn + Gherkin 格式

用户故事包含：

用例（Mike Cohn 格式）：

• 作为 [用户画像/角色]
• 我想要 [为达成结果而执行的操作]
• 以便 [期望的结果]

验收标准（Gherkin 格式）：

• 场景： [场景的简要描述]
• 假设： [初始上下文或前置条件]
• 并且假设： [其他前置条件]
• 当： [触发操作的事件]
• 那么： [预期结果]

这种结构为何有效

• 以用户为中心： 强制关注谁会受益以及原因
• 以成果为导向： “以便”强调交付的价值，而不只是操作本身
• 可测试： Gherkin 验收标准具体且可验证
• 便于讨论： 故事是讨论的开端，而不是最终规格说明
• 共享语言： 产品、工程和 QA 团队都能理解这种格式

反模式（本格式不适用于什么）

• 不是任务： “作为一名开发者，我想重构数据库”（这是技术任务，不是用户价值）
• 不是功能列表： “我想要仪表板、报告和分析功能”（范围太大，需要拆分）
• 不能含糊： “我想要更好的体验”（无法衡量，也没有明确结果）
• 不是合同： 故事是讨论的占位内容，不是敲定的规格说明

适用场景

• 将用户需求转化为开发工作
• 梳理待办事项和规划冲刺
• 向工程和设计团队传达价值
• 确保开发开始前已有可测试的验收标准

不适用场景

• 纯技术债务或重构（改用工程任务）
• 故事范围过大时（先拆分，参见 skills/user-story-splitting/SKILL.md）
• 尚未理解用户问题时（先编写问题陈述）

---

应用

步骤 1：收集上下文

编写故事前，请确保已了解：

• 用户画像： 这是为谁设计的？（参见 skills/proto-persona/SKILL.md）
• 问题理解： 这要解决什么需求？（参见 skills/problem-statement/SKILL.md）
• 期望结果： 成功是什么样的？
• 约束： 技术、时间或范围限制

如果缺少上下文： 先进行探索性访谈或问题验证工作。

---

可选辅助脚本（模板生成器）

如果想生成格式统一的 Markdown 框架，可以通过 CLI 输入生成。此脚本具有确定性，不会获取数据或写入文件。

python3 scripts/user-story-template.py --persona \"trial user\" --action \"log in with Google\" --outcome \"access the app without creating a new password\"

---

步骤 2：编写用例

使用 template.md 获取完整的填写结构。

填写模板：

### User Story [ID]:

- **Summary:** [Brief, memorable title focused on value to the user]

#### Use Case:
- **As a** [user name if available, otherwise persona, otherwise role]
- **I want to** [action user takes to get to outcome]
- **so that** [desired outcome]

质量检查：

• “作为”是否具体： 是具体的角色（例如“试用用户”），还是泛指“用户”？
• “我想要”是否清晰： 这是用户采取的行动，还是你正在构建的功能？
• “以便”是否说明结果： 这是否解释了用户的动机？还是只是在重复行动？

常见错误：

• ❌ “作为用户，我想要一个登录按钮，以便我可以登录”（重复描述行动）
• ✅ “作为试用用户，我想要使用 Google 登录，以便无需创建新密码即可访问应用”

---

步骤 3：编写验收标准

填写模板：

#### Acceptance Criteria:

- **Scenario:** [Brief, human-readable scenario describing value]
- **Given:** [Initial context or precondition]
- **and Given:** [Additional context or preconditions]
- **and Given:** [Additional context as needed]
- **and Given:** [UI-focused context ensuring 'When' can happen]
- **and Given:** [Outcomes-focused context ensuring 'Then' is delivered]
- **When:** [Event that triggers the action—aligns with 'I want to']
- **Then:** [Expected outcome—aligns with 'so that']

质量检查：

• 可以有多个 Given： 前置条件可以叠加（例如“Given 我已登录” + “Given 我的购物车中有商品”）
• 只能有一个 When： 如果需要多个“When”语句，你很可能有多个故事，应将其拆分
• 只能有一个 Then： 如果需要多个“Then”语句，你很可能有多个故事，应将其拆分
• 是否一致： “When”是否对应“我想要”？“Then”是否对应“以便”？

警示信号：

• 多个 When/Then： 表明范围蔓延，应拆分故事（参见 skills/user-story-splitting/SKILL.md）
• 含糊的 Then： “Then 我能感受到性能提升”（无法衡量，应具体说明）

---

步骤 4：添加摘要

编写简短、易记的摘要，概括该故事的价值：

- **Summary:** [Brief, human-readable title]

示例：

• ✅ “为试用用户启用 Google 登录，降低注册阻力”
• ✅ “批量删除商品，为高级用户节省时间”
• ❌ “添加删除按钮”（以功能为中心，而非以价值为中心）

---

步骤 5：验证并完善

• 向团队大声朗读： 每个人是否都理解了谁、做什么、为什么？
• 测试验收标准： QA 能否据此编写测试用例？
• 检查是否需要拆分： 如果故事感觉太大，请使用 skills/user-story-splitting/SKILL.md
• 确保可测试： 你能否证明“Then”已经发生？

---

示例

完整示例（包括好的、不好的以及需要拆分的故事）请参见 examples/sample.md。

迷你示例摘录：

### User Story 042:

- **Summary:** Enable Google login for trial users to reduce signup friction

#### Use Case:
- **As a** trial user visiting the app for the first time
- **I want to** log in using my Google account
- **so that** I can access the app without creating and remembering a new password

#### Acceptance Criteria:
- **Scenario:** First-time trial user logs in via Google OAuth
- **Given:** I am on the login page
- **and Given:** I have a login account
- **When:** I click the "Sign in with Google" button and authorize the app
- **Then:** I am logged into the app and redirected to the onboarding flow

---

常见陷阱

陷阱 1：伪装成用户故事的技术任务

表现： “作为开发者，我想要重构 API，以便代码更简洁”

后果： 这是工程任务，不是用户故事，不会带来用户价值。

解决方法： 如果没有用户层面的结果，就不是用户故事，应改用工程任务或技术债工单。

---

陷阱 2：“作为用户”（过于笼统）

表现： 每个故事都以“作为用户”开头

后果： 角色不明确。不同用户有不同需求。

解决方法： 使用具体角色：“作为试用用户”“作为付费订阅者”“作为管理员”等。（参见 skills/proto-persona/SKILL.md）

---

陷阱 3：“以便”只是重复“我想要”

表现： “我想要点击保存按钮，以便保存我的工作”

后果： 没有说明用户关心的原因，只是重复了行动。

解决方法： 深入挖掘动机：“以便页面崩溃时我不会丢失进度”（真实结果）。

---

陷阱 4：多个 When/Then 语句

表现： 验收标准中有 5 个“When”语句和 5 个“Then”语句

后果： 故事太大，很可能捆绑了多个功能。

解决方法： 使用 skills/user-story-splitting/SKILL.md 拆分故事。每对 When/Then 都应该成为独立的故事（或至少评估是否需要拆分）。

---

陷阱 5：无法测试的验收标准

表现： “Then 用户体验更好”或“Then 速度更快”

后果： QA 无法验证是否成功。“完成”的定义含糊不清。

解决方法： 使其可衡量：“Then 页面会在 2 秒内加载”或“Then 用户会看到成功确认消息”。

---

参考资料

相关技能

• skills/user-story-splitting/SKILL.md — 如何将大型故事拆分为更小的故事
• skills/proto-persona/SKILL.md — 定义“As a [persona]”部分
• skills/problem-statement/SKILL.md — 故事应解决已验证的问题
• skills/epic-hypothesis/SKILL.md — Epic 分解为用户故事

可选辅助工具

• skills/user-story/scripts/user-story-template.py — 确定性 Markdown 框架生成器（不访问网络）

外部框架

• Mike Cohn，User Stories Applied（2004）——“As a / I want / so that”格式的起源
• Gherkin（Cucumber）——“Given/When/Then”验收标准格式
• INVEST 标准（Independent、Negotiable、Valuable、Estimable、Small、Testable）

Dean 的作品

• [如适用，链接到 Dean Peters 的相关 Substack 文章]

来源

• 改编自 https://github.com/deanpeters/product-manager-prompts 仓库中的 prompts/user-story-prompt-template.md。

---

技能类型： 组件 建议文件名： user-story.md 建议放置位置： /skills/components/ 依赖项： 引用了 skills/proto-persona/SKILL.md、skills/problem-statement/SKILL.md 使用方： skills/user-story-splitting/SKILL.md、skills/epic-hypothesis/SKILL.md