AI Skills
user-story

user-story

热门

结合 Mike Cohn 格式与 Gherkin 验收标准编写用户故事（User Story）。适用于将用户需求转化为具有明确产出与可测试条件的、可直接用于开发交付的工作项。

5972Star
734Fork
更新于 2026/7/17
获取 Skill源代码

相关 Skills

agent-implementer-sparc-coder7.2万webapp-testing6.9万camsnap39万
SKILL.md
只读
名称
user-story
描述

结合 Mike Cohn 格式与 Gherkin 验收标准编写用户故事（User Story）。适用于将用户需求转化为具有明确产出与可测试条件的、可直接用于开发交付的工作项。

Purpose

创建清晰简练的用户故事，将 Mike Cohn 的用户故事格式与 Gherkin 风格的验收标准相结合。用于将用户需求转化为聚焦产出、可落地的开发工作，确保产品与研发团队达成共识，并提供可测试的成功标准。

这不是一份功能规格说明书（Feature Spec），而是一个讨论的起点。它记录了谁将受益、他们试图做什么、为什么这很重要，以及你将如何验证其效果。

Input

Works best with: 该 Story 所承载的功能或用户需求。
Also useful: 用户角色、他们期望的产出，以及验收标准必须覆盖的边界情况（Edge Cases）。

在调用时直接传入的任何内容——无论是 Skill 名称后面的文本、粘贴的上下文信息，还是附带的 ARGUMENTS: 行——都将被视为已提供的答案。直接使用这些信息并跳过已覆盖的内容，切勿重复提问。

空手而来？也没问题。 本 Skill 会在撰写 Story 和 Gherkin 标准之前，先询问用户是谁以及他们想要达成什么目标。

调用示例： Write user stories for password reset via SMS for our banking app — include the lockout edge case.

Key Concepts

The Mike Cohn + Gherkin Format

一个用户故事包含以下部分：

用例（Mike Cohn 格式）：

  • As a [用户画像/角色]
  • I want to [为实现目标而采取的行动]
  • so that [期望的产出/价值]

验收标准（Gherkin 格式）：

  • Scenario: [场景的简短描述]
  • Given: [初始上下文或前置条件]
  • and Given: [额外的前置条件]
  • When: [触发该操作的事件]
  • Then: [预期结果/产出]

Why This Structure Works

  • 以用户为中心： 强制聚焦于谁能受益以及为什么受益
  • 聚焦产出： "so that（以便于）"强调的是交付的价值，而不仅仅是操作本身
  • 可测试： Gherkin 验收标准具体且易于验证
  • 具沟通性： Story 是开启讨论的契机，而非不可更改的终稿规格
  • 统一语言： 产品、研发和 QA 都能理解这一格式

Anti-Patterns (What This Is NOT)

  • 非技术任务： "As a developer, I want to refactor the database"（这是技术任务，并非用户价值）
  • 非功能列表： "I want dashboards, reports, and analytics"（范围太大——需要拆分）
  • 非模糊描述： "I want a better experience"（无法衡量，没有明确产出）
  • 非严肃契约： Story 是沟通交流的载体，而非死板定型的规格书

When to Use This

  • 将用户需求转化为开发任务
  • Backlog 梳理（Grooming）与 Sprint 迭代规划
  • 向研发和设计团队传递需求价值
  • 确保在开发前已具备可测试的验收标准

When NOT to Use This

  • 纯技术债或代码重构（请改用工程技术任务/Tech Task）
  • 当 Story 过于庞大时（请先拆分——参考 skills/user-story-splitting/SKILL.md）
  • 在尚未充分理解用户问题之前（请先编写问题陈述/Problem Statement）

Application

Step 1: Gather Context

在编写 Story 之前，请确保已具备以下信息：

  • 用户画像（Persona）： 这是为谁打造的？（参考 skills/proto-persona/SKILL.md）
  • 问题认知： 这解决了什么需求？（参考 skills/problem-statement/SKILL.md）
  • 期望产出： 成功具体表现为什么？
  • 约束条件： 技术、时间或范围方面的限制

若缺少上下文： 请先进行用户调研访谈或问题验证工作。

Optional Helper Script (Template Generator)

如果你需要生成结构一致的 Markdown 存根（Stub），可以通过 CLI 输入运行脚本生成。该脚本结果确定，不会发起网络请求或写入文件。

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

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

填写模板：

### User Story [ID]:

- **Summary:** [简短且易记的标题，聚焦于给用户带来的价值]

#### Use Case:
- **As a** [具体用户名（若有），或用户画像，或角色]
- **I want to** [用户为达成目标所采取的行动]
- **so that** [期望的产出/价值]

质量自查：

  • "As a" 的具体程度： 这是一个具体的画像（例如 "trial user"），还是泛泛的描述（"user"）？
  • "I want to" 的清晰度： 这是用户采取的行动，还是你要构建的功能？
  • "So that" 的价值阐述： 这是否解释了用户的真实动机？还是仅仅把操作重新说了一遍？

常见错误示范：

  • ❌ "As a user, I want a login button, so that I can log in"（只是重复阐述操作）
  • ✅ "As a trial user, I want to log in with Google, so that I can access the app without creating a new password"

Step 3: Write the Acceptance Criteria

填写模板：

#### Acceptance Criteria:

- **Scenario:** [描述价值的简短、易读的场景]
- **Given:** [初始上下文或前置条件]
- **and Given:** [补充上下文或前置条件]
- **and Given:** [根据需要补充的上下文]
- **and Given:** [聚焦于 UI 的上下文，确保 'When' 能够发生]
- **and Given:** [聚焦于产出的上下文，确保 'Then' 能够交付]
- **When:** [触发操作的事件——与 'I want to' 保持一致]
- **Then:** [预期结果/产出——与 'so that' 保持一致]

质量自查：

  • 允许有多个 Given： 前置条件可以层层叠加（例如 "Given 我已登录" + "Given 我的购物车中有商品"）
  • 只能有一个 When： 如果你需要多个 "When" 语句，说明这大概率包含多个 Story——请进行拆分
  • 只能有一个 Then： 如果你需要多个 "Then" 语句，说明这大概率包含多个 Story——请进行拆分
  • 对齐检查： "When" 是否对应 "I want to"？"Then" 是否对应 "so that"？

危险信号：

  • 存在多个 When/Then： 意味着需求蔓延（Scope Creep）——请拆分 Story（参考 skills/user-story-splitting/SKILL.md）
  • 含糊不清的 Then： "Then 体验得到了提升"（无法衡量——请具体化）

Step 4: Add a Summary

撰写简短且易记的概要，精准概括 Story 的核心价值：

- **Summary:** [简短、易读的标题]

示例：

  • ✅ "Enable Google login for trial users to reduce signup friction"
  • ✅ "Bulk delete items to save time for power users"
  • ❌ "Add delete button"（以功能为中心，而非以价值为中心）

Step 5: Validate and Refine

  • 大声读给团队听： 每个人是否都明确了谁、做什么、为什么做？
  • 测试验收标准： QA 能否据此直接编写测试用例？
  • 评估是否需要拆分： 如果感觉 Story 膨胀过大，使用 skills/user-story-splitting/SKILL.md 进行拆分
  • 确保可测试性： 你能否验证 "Then" 的结果确实发生了？

Examples

完整示例（包含优秀示例、反面教材以及需要拆分的案例）请参阅 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

Common Pitfalls

Pitfall 1: Technical Tasks Disguised as User Stories

症状： "As a developer, I want to refactor the API, so that the code is cleaner"

后果： 这是工程技术任务，而非用户故事。它没有交付任何直接的用户价值。

解法： 如果没有用户层面的产出，就不要写成用户故事——直接创建工程技术任务或技术债工单（Tech Debt Ticket）。

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

症状： 每个 Story 都以 "As a user" 开头

后果： 用户画像模糊。不同的用户群体有着截然不同的需求。

解法： 使用具体的角色画像："As a trial user"、"As a paid subscriber"、"As an admin" 等（参考 skills/proto-persona/SKILL.md）。

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

症状： "I want to click the save button, so that I can save my work"

后果： 根本没有揭示用户为什么在乎。纯粹是把操作步骤又复述了一遍。

解法： 挖掘背后的真实动机："so that I don't lose my progress if the page crashes"（这才是真正的产出）。

Pitfall 4: Multiple When/Then Statements

症状： 验收标准里挤进了 5 个 "When" 和 5 个 "Then"

后果： Story 过于臃肿。很可能是把多个功能打包塞在了一起。

解法： 使用 skills/user-story-splitting/SKILL.md 进行 Story 拆分。每一对 When/Then 应当独立为一个 Story（或至少评估是否需要拆分）。

Pitfall 5: Untestable Acceptance Criteria

症状： "Then the user has a better experience" 或 "Then it's faster"

后果： QA 无法验证是否成功完成。"Done" 的定义模糊不清。

解法： 必须明确可衡量："Then the page loads in under 2 seconds" 或 "Then the user sees a success confirmation message"。

References

Related Skills

  • skills/user-story-splitting/SKILL.md — 如何将大型 Story 拆分为更小的单元
  • skills/proto-persona/SKILL.md — 定义 "As a [persona]" 部分
  • skills/problem-statement/SKILL.md — Story 应服务于已验证的问题
  • skills/epic-hypothesis/SKILL.md — Epic 拆解为具体的 User Story

Optional Helpers

  • skills/user-story/scripts/user-story-template.py — 确定性 Markdown 存根生成器（无需网络访问）

External Frameworks

  • 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's Work

  • [若适用，此处链接至 Dean Peters 的 Substack 相关文章]

Provenance

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

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