Back to Details

user-story

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Purpose

目的

Create clear, concise user stories that combine Mike Cohn's user story format with Gherkin-style acceptance criteria. Use this to translate user needs into actionable development work that focuses on outcomes, ensures shared understanding between product and engineering, and provides testable success criteria.
This is not a feature spec—it's a conversation starter that captures who benefits, what they're trying to do, why it matters, and how you'll know it works.
创建结合Mike Cohn用户故事格式与Gherkin风格验收标准的清晰、简洁的用户故事。使用该方法将用户需求转化为可执行的开发工作，聚焦于成果交付，确保产品与开发团队达成共识，并提供可测试的成功标准。
这不是功能规格说明——它是对话的起点，涵盖了谁将从中受益、用户想要做什么、为什么这很重要以及如何验证功能生效。

Key Concepts

核心概念

The Mike Cohn + Gherkin Format

Mike Cohn + Gherkin 格式

A user story combines:
Use Case (Mike Cohn format):
  • As a [user persona/role]
  • I want to [action to achieve outcome]
  • so that [desired outcome]
Acceptance Criteria (Gherkin format):
  • Scenario: [Brief description of the scenario]
  • Given: [Initial context or preconditions]
  • and Given: [Additional preconditions]
  • When: [Event that triggers the action]
  • Then: [Expected outcome]
用户故事由两部分组成：
用例（Mike Cohn格式）：
  • 作为 [用户角色/人物画像]
  • 我想要 [实现成果的操作]
  • 以便 [期望的成果]
验收标准（Gherkin格式）：
  • Scenario: [场景的简要描述]
  • Given: [初始上下文或前置条件]
  • and Given: [额外的前置条件]
  • When: [触发操作的事件]
  • Then: [期望的成果]

Why This Structure Works

该结构的优势

  • User-centric: Forces focus on who benefits and why
  • Outcome-focused: "So that" emphasizes the value delivered, not just the action
  • Testable: Gherkin acceptance criteria are concrete and verifiable
  • Conversational: Story is the opening for discussion, not the final spec
  • Shared language: Product, engineering, and QA all understand the format
  • 以用户为中心： 强制聚焦于受益人群及其需求动机
  • 成果导向： "以便"部分强调交付的价值，而非单纯的操作
  • 可测试性： Gherkin格式的验收标准具体且可验证
  • 对话式： 故事是讨论的开端，而非最终的规格说明
  • 通用语言： 产品、开发与QA团队都能理解该格式

Anti-Patterns (What This Is NOT)

反模式（需避免的情况）

  • Not a task: "As a developer, I want to refactor the database" (this is a tech task, not user value)
  • Not a feature list: "I want dashboards, reports, and analytics" (this is too big—needs splitting)
  • Not vague: "I want a better experience" (unmeasurable, no clear outcome)
  • Not a contract: Stories are placeholders for conversation, not locked-in specs
  • 不是任务： "作为开发者，我想要重构数据库"（这是技术任务，不涉及用户价值）
  • 不是功能列表： "我想要仪表盘、报表和分析功能"（范围过大，需要拆分）
  • 表述模糊： "我想要更好的体验"（无法衡量，没有明确成果）
  • 不是契约： 故事是对话的占位符，而非锁定的规格说明

When to Use This

适用场景

  • Translating user needs into development work
  • Backlog grooming and sprint planning
  • Communicating value to engineering and design
  • Ensuring testable acceptance criteria exist before development
  • 将用户需求转化为开发工作
  • Backlog grooming与sprint planning
  • 向开发与设计团队传递价值
  • 确保开发前存在可测试的验收标准

When NOT to Use This

不适用场景

  • For pure technical debt or refactoring (use engineering tasks instead)
  • When stories are too large (split first—see 
    skills/user-story-splitting/SKILL.md
    )
  • Before understanding the user problem (write a problem statement first)
  • 纯技术债务或重构工作（使用开发任务替代）
  • 故事范围过大（先拆分，参考
    skills/user-story-splitting/SKILL.md
    ）
  • 未明确用户问题前（先撰写问题陈述）

Application

实践步骤

Step 1: Gather Context

步骤1：收集上下文信息

Before writing a story, ensure you have:
  • User persona: Who is this for? (reference 
    skills/proto-persona/SKILL.md
    )
  • Problem understanding: What need does this address? (reference 
    skills/problem-statement/SKILL.md
    )
  • Desired outcome: What does success look like?
  • Constraints: Technical, time, or scope limitations
If missing context: Run discovery interviews or problem validation work first.
在撰写故事前，确保你已明确：
  • 用户画像： 该功能面向谁？（参考
    skills/proto-persona/SKILL.md
    ）
  • 问题理解： 该功能解决什么需求？（参考
    skills/problem-statement/SKILL.md
    ）
  • 期望成果： 成功的标准是什么？
  • 约束条件： 技术、时间或范围限制
若缺失上下文： 先开展用户调研或问题验证工作。

Optional Helper Script (Template Generator)

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

If you want a consistent Markdown stub, you can generate one from CLI inputs. This script is deterministic and does not fetch data or write files.
bash
python3 scripts/user-story-template.py --persona \"trial user\" --action \"log in with Google\" --outcome \"access the app without creating a new password\"
如果你需要统一的Markdown模板，可以通过CLI输入生成。该脚本为确定性脚本，不会获取数据或写入文件。
bash
python3 scripts/user-story-template.py --persona \"trial user\" --action \"log in with Google\" --outcome \"access the app without creating a new password\"

Step 2: Write the Use Case

步骤2：撰写用例

Use 
template.md
for the full fill-in structure.
Fill in the template:
markdown
undefined
使用
template.md
获取完整的填充式结构。
填充模板：
markdown
undefined

User Story [ID]:

User Story [ID]:

  • Summary: [Brief, memorable title focused on value to the user]
  • Summary: [聚焦用户价值的简短易记标题]

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]

**Quality checks:**
- **"As a" specificity:** Is this a specific persona (e.g., "trial user") or generic ("user")?
- **"I want to" clarity:** Is this an action the user takes, or a feature you're building?
- **"So that" outcome:** Does this explain the user's motivation? Or is it just restating the action?

**Common mistakes:**
- ❌ "As a user, I want a login button, so that I can log in" (restating the action)
- ✅ "As a trial user, I want to log in with Google, so that I can access the app without creating a new password"

---
  • 作为 [如有具体用户名则填写，否则填用户画像，再否则填角色]
  • 我想要 [用户为达成成果需执行的操作]
  • 以便 [期望的成果]

**质量检查：**
- **"作为"的具体性：** 是具体的用户画像（如"试用用户"）还是通用的"用户"？
- **"我想要"的清晰度：** 是用户执行的操作，还是你要开发的功能？
- **"以便"的成果导向：** 是否解释了用户的动机？还是仅仅重复操作内容？

**常见错误：**
- ❌ "作为用户，我想要一个登录按钮，以便我可以登录"（重复操作内容）
- ✅ "作为试用用户，我想要通过Google登录，以便无需创建新密码即可访问应用"

---

Step 3: Write the Acceptance Criteria

步骤3：撰写验收标准

Fill in the template:
markdown
undefined
填充模板：
markdown
undefined

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']

**Quality checks:**
- **Multiple Givens are okay:** Preconditions stack up (e.g., "Given I'm logged in" + "Given I have items in my cart")
- **Only one When:** If you need multiple "When" statements, you likely have multiple stories—split them
- **Only one Then:** If you need multiple "Then" statements, you likely have multiple stories—split them
- **Alignment:** Does "When" match "I want to"? Does "Then" match "so that"?

**Red flags:**
- **Multiple Whens/Thens:** Sign of scope creep—split the story (reference `skills/user-story-splitting/SKILL.md`)
- **Vague Thens:** "Then I see improved performance" (unmeasurable—make it specific)

---
  • Scenario: [描述价值的简短易懂场景]
  • Given: [初始上下文或前置条件]
  • and Given: [额外的上下文或前置条件]
  • and Given: [按需添加更多上下文]
  • and Given: [确保"When"可执行的UI相关上下文]
  • and Given: [确保"Then"可达成的成果相关上下文]
  • When: [触发操作的事件——与"我想要"部分对齐]
  • Then: [期望的成果——与"以便"部分对齐]

**质量检查：**
- **允许多个Given：** 前置条件可以叠加（如"Given我已登录" + "Given我的购物车中有商品"）
- **仅一个When：** 若需要多个\"When\"语句，说明你可能有多个故事——需要拆分
- **仅一个Then：** 若需要多个\"Then\"语句，说明你可能有多个故事——需要拆分
- **对齐性：** "When"是否与\"我想要\"匹配？"Then"是否与\"以便\"匹配？

**警示信号：**
- **多个When/Then语句：** 故事范围过大，可能捆绑了多个功能
- **模糊的Then：** "Then我看到性能提升"（无法衡量——需具体化）

---

Step 4: Add a Summary

步骤4：添加摘要

Write a short, memorable summary that captures the story's value:
markdown
- **Summary:** [Brief, human-readable title]
Examples:
  • ✅ "Enable Google login for trial users to reduce signup friction"
  • ✅ "Bulk delete items to save time for power users"
  • ❌ "Add delete button" (feature-centric, not value-centric)
撰写简短易记的摘要，体现故事的价值：
markdown
- **Summary:** [简短易懂的标题]
示例：
  • ✅ "为试用用户启用Google登录以降低注册门槛"
  • ✅ "批量删除功能为高级用户节省时间"
  • ❌ "添加删除按钮"（以功能为中心，而非价值为中心）

Step 5: Validate and Refine

步骤5：验证与优化

  • Read aloud to the team: Does everyone understand who, what, why?
  • Test acceptance criteria: Can QA write test cases from this?
  • Check for splitting: If the story feels too big, use 
    skills/user-story-splitting/SKILL.md
  • Ensure testability: Can you prove "Then" happened?
  • 向团队朗读： 所有人是否都理解用户、操作与动机？
  • 测试验收标准： QA能否基于此编写测试用例？
  • 检查拆分必要性： 若故事感觉过大，使用
    skills/user-story-splitting/SKILL.md
    进行拆分
  • 确保可测试性： 能否证明"Then"的结果已达成？

Examples

示例

See 
examples/sample.md
for full examples (good, bad, and split-needed stories).
Mini example excerpt:
markdown
undefined
完整示例请查看
examples/sample.md
（包含优秀、待改进与需拆分的故事）。
迷你示例片段：
markdown
undefined

User Story 042:

User Story 042:

  • Summary: Enable Google login for trial users to reduce signup friction
  • Summary: 为试用用户启用Google登录以降低注册门槛

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
  • 作为 首次访问应用的试用用户
  • 我想要 使用Google账户登录
  • 以便 无需创建并记住新密码即可访问应用

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

---
  • Scenario: 首次试用用户通过Google OAuth登录
  • Given: 我在登录页面
  • and Given: 我拥有Google账户
  • When: 我点击"Sign in with Google"按钮并授权应用
  • Then: 我成功登录应用并被重定向至引导流程

---

Common Pitfalls

常见陷阱

Pitfall 1: Technical Tasks Disguised as User Stories

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

Symptom: "As a developer, I want to refactor the API, so that the code is cleaner"
Consequence: This is an engineering task, not a user story. No user value is delivered.
Fix: If there's no user outcome, it's not a user story—use an engineering task or tech debt ticket instead.
症状： "作为开发者，我想要重构API，以便代码更整洁"
后果： 这是开发任务，而非用户故事，不传递用户价值。
解决方法： 若没有用户成果，就不是用户故事——使用开发任务或技术债务工单替代。

Pitfall 2: "As a User" (Too Generic)

陷阱2："作为用户"（过于通用）

Symptom: Every story starts with "As a user"
Consequence: No persona clarity. Different users have different needs.
Fix: Use specific personas: "As a trial user," "As a paid subscriber," "As an admin," etc. (reference 
skills/proto-persona/SKILL.md
)
症状： 所有故事都以"作为用户"开头
后果： 缺乏用户画像清晰度，不同用户的需求存在差异。
解决方法： 使用具体的用户画像："作为试用用户"、"作为付费订阅用户"、"作为管理员"等（参考
skills/proto-persona/SKILL.md
）

Pitfall 3: "So That" Restates "I Want To"

陷阱3："以便"重复"我想要"的内容

Symptom: "I want to click the save button, so that I can save my work"
Consequence: No insight into why the user cares. Just restating the action.
Fix: Dig into the motivation: "so that I don't lose my progress if the page crashes" (real outcome).
症状： "我想要点击保存按钮，以便我可以保存工作"
后果： 无法洞察用户关心的核心动机，只是重复操作内容。
解决方法： 深挖动机："以便页面崩溃时我不会丢失进度"（真实成果）

Pitfall 4: Multiple When/Then Statements

陷阱4：多个When/Then语句

Symptom: Acceptance criteria with 5 "When" statements and 5 "Then" statements
Consequence: Story is too big. Likely multiple features bundled together.
Fix: Split the story using 
skills/user-story-splitting/SKILL.md
. Each When/Then pair should be its own story (or at least evaluated for splitting).
症状： 验收标准包含5个"When"语句与5个"Then"语句
后果： 故事范围过大，可能捆绑了多个功能。
解决方法： 使用
skills/user-story-splitting/SKILL.md
拆分故事。每个When/Then对都应成为独立的故事（或至少评估拆分必要性）。

Pitfall 5: Untestable Acceptance Criteria

陷阱5：不可测试的验收标准

Symptom: "Then the user has a better experience" or "Then it's faster"
Consequence: QA can't verify success. Ambiguous definition of "done."
Fix: Make it measurable: "Then the page loads in under 2 seconds" or "Then the user sees a success confirmation message."
症状： "Then用户获得更好的体验"或"Then速度更快"
后果： QA无法验证成功，"完成"的定义模糊。
解决方法： 使其可衡量："Then页面加载时间少于2秒"或"Then用户看到成功确认消息"

References

参考资料

Related Skills

相关技能

  • skills/user-story-splitting/SKILL.md
    — How to break large stories into smaller ones
  • skills/proto-persona/SKILL.md
    — Defines the "As a [persona]" section
  • skills/problem-statement/SKILL.md
    — Stories should address validated problems
  • skills/epic-hypothesis/SKILL.md
    — Epics decompose into user stories
  • skills/user-story-splitting/SKILL.md
    —— 如何将大型故事拆分为小型故事
  • skills/proto-persona/SKILL.md
    —— 定义"作为[用户画像]"部分
  • skills/problem-statement/SKILL.md
    —— 故事应解决经过验证的问题
  • skills/epic-hypothesis/SKILL.md
    —— 史诗需求可拆分为用户故事

Optional Helpers

可选辅助工具

  • skills/user-story/scripts/user-story-template.py
    — Deterministic Markdown stub generator (no network access)
  • skills/user-story/scripts/user-story-template.py
    —— 确定性Markdown模板生成器（无网络访问）

External Frameworks

外部框架

  • Mike Cohn, User Stories Applied (2004) — Origin of the "As a / I want / so that" format
  • Gherkin (Cucumber) — "Given/When/Then" acceptance criteria format
  • INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
  • Mike Cohn，User Stories Applied（2004）—— "作为/我想要/以便"格式的起源
  • Gherkin (Cucumber) —— "Given/When/Then"验收标准格式
  • INVEST准则（Independent, Negotiable, Valuable, Estimable, Small, Testable）

Dean's Work

Dean的相关工作

  • [Link to relevant Dean Peters' Substack articles if applicable]
  • [相关Dean Peters的Substack文章链接（如适用）]

Provenance

来源

  • Adapted from 
    prompts/user-story-prompt-template.md
    in the 
    https://github.com/deanpeters/product-manager-prompts
    repo.
Skill type: Component Suggested filename: 
user-story.md
Suggested placement: 
/skills/components/
Dependencies: References 
skills/proto-persona/SKILL.md
, 
skills/problem-statement/SKILL.md
Used by: 
skills/user-story-splitting/SKILL.md
, 
skills/epic-hypothesis/SKILL.md
  • 改编自
    https://github.com/deanpeters/product-manager-prompts
    仓库中的
    prompts/user-story-prompt-template.md
技能类型： Component 建议文件名： 
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