---

name: user-story-writer language: zh description: "撰写结构良好、带验收标准和边界情况的用户故事。当被要求写用户故事、根据功能说明建任务、把 PRD 转成故事，或写验收标准时使用。产出可以直接估算的标准格式故事，附清楚的验收标准、边界情况和完成定义。"

user-story-writer 的简体中文翻译，英文版本为规范版本。

用户故事撰写

这个技能根据功能说明、PRD 的某一部分或口头描述，产出可以直接使用的用户故事。每个故事都遵循标准格式：清楚的谁 / 做什么 / 为什么，按 Given / When / Then（假如 / 当 / 那么）格式写的行为验收标准、边界情况和完成定义。产出可以直接粘贴到 Jira、Linear 或你的规划工具中。

所需输入

如未提供，请向用户询问：

• 要拆成故事的功能或改动：粘贴说明、PRD 部分，或描述功能
• 涉及的用户类型 / 角色（例如管理员、最终用户、访客、API 调用方）
• 范围：写一个故事，还是把一个史诗拆成完整的一组故事？
• 验收标准格式偏好：Given / When / Then、要点清单，还是两者都要？
• 技术约束或说明：工程团队提出的、应当影响故事的任何事项

输出结构

每个故事：

---

故事：[简短标题，动词加名词，例如"按日期范围筛选搜索结果"]

史诗： [所属史诗名称，例如"高级搜索"] 故事编号： [Jira / Linear 编号，还没创建就留空] 优先级： [P1 / P2 / P3] 故事点： [留空，由工程团队估算]

---

用户故事

作为 [具体的用户类型，不要写"用户"]， 我想要 [他们想采取的具体行动]， 以便 [他们得到的结果：业务价值，而不是功能描述]。

示例：

作为客户经理， 我想要按最近联系日期筛选我的客户列表， 以便快速找出 30 天以上没有联系过的客户，并优先跟进。

---

背景

[1 到 3 句用户故事本身没有的背景：这个故事什么时候重要、是什么触发了这个需要、它如何融入更大的流程。这能帮助工程师在提问之前就理解为什么。]

---

验收标准

格式：Given / When / Then（假如 / 当 / 那么）

每条标准只测试一个具体行为。每个可观察的结果写一条，而不是整个功能只写一条。

AC1：[这条标准的简短名称]

假如 [初始状态或背景]
当 [用户行动]
那么 [可观察的系统行为]

AC2：[简短名称]

假如 [...]
当 [...]
那么 [...]

AC3：[简短名称]

假如 [...]
当 [...]
那么 [...]

---

边界情况

[列出不明显但必须处理的场景。它们会成为额外的验收标准或给工程团队的说明。]

• [边界情况 1]： [例如用户应用的日期筛选返回 0 条结果：显示空状态，附清楚的提示和"清除筛选"操作]
• [边界情况 2]： [例如用户有超过 10,000 个客户：筛选不能让加载时间增加超过 200 毫秒]
• [边界情况 3]： [例如日期筛选在刷新页面后保留，或者如果决定不保留，就明确写明不保留]
• [权限边界情况]： [例如只读用户能看到筛选，但不能保存筛选预设]

---

不在范围内

[明确写出这个故事不包括什么：防止范围蔓延，并说明下一个故事从哪里开始。]

• 保存和分享筛选预设（另一个故事，见 [故事 X]）
• 对筛选结果的批量操作
• 把筛选后的客户列表导出为 CSV

---

完成定义

• 所有验收标准都通过
• 边界情况已处理（或已明确推迟并新建了任务）
• 每条验收标准都有单元测试
• 在移动端视口下可用（如适用）
• 无障碍：可键盘操作，兼容读屏软件
• 错误状态已处理，文案已确认
• 产品和设计已在预发环境审阅
• 生产构建中没有控制台错误

---

史诗拆解模板

如果用户提供的是史诗或功能说明，先把它拆成完整的一组故事，再逐个撰写：

史诗： [名称] 目标： [完成这个史诗带来什么结果？] 故事：

#	故事	说明	依赖
1	[核心正常路径故事：能交付价值的最简单版本]
2	[校验 / 错误处理故事]		依赖 #1
3	[边界情况或高级用户故事]		依赖 #1
4	[管理员或配置故事]
5	[性能或规模故事，如适用]		依赖 #1

建议的迭代顺序： [哪些故事是 MVP 的 P1？哪些可以放到之后的迭代？]

---

常见的故事反模式及修正

在交给工程团队之前，用这些来审查故事：

反模式	例子	修正
故事里写了方案	"作为用户，我想要一个下拉筛选框"	去掉界面决定："作为用户，我想要按日期范围筛选"
含糊的"以便"	"以便更好用"	写具体："以便我不用逐条打开记录就能安排跟进优先级"
太大	一个故事涵盖 5 个不同的用户流程	按流程拆成多个故事
没有验收标准	故事只有描述	工程开始前至少加 3 条 Given / When / Then 标准
验收标准测试方案而不是行为	"假如下拉框已打开，当我选择一个选项"	测试结果："假如我应用了日期筛选，当我查看结果，那么只显示在该日期范围内最近联系过的客户"
缺少空状态	没有关于 0 条结果时怎么办的标准	加上：空状态是功能的一部分
缺少错误状态	没有关于网络失败或无效输入的标准	明确加上错误处理的验收标准

---

示例：一个功能的完整故事集

功能说明： "允许用户把发票历史导出为 PDF 或 CSV"

---

故事 1：把发票列表导出为 CSV

作为财务管理员， 我想要把我的发票历史导出为 CSV 文件， 以便不用手动录入就能导入我们的会计软件。

AC1：导出成功

假如 我在发票页面，且至少有一张发票
当 我点击"导出"并选择"CSV"
那么 下载一个 CSV 文件，包含所有可见发票，列为：发票编号、日期、金额、状态、客户名称

AC2：空状态

假如 我在发票页面，且没有任何发票
当 我点击"导出"
那么 导出按钮不可用，提示显示"没有可导出的发票"

AC3：筛选后导出

假如 我已应用日期筛选，只显示 2026 年 1 月的发票
当 我点击"导出"并选择"CSV"
那么 导出内容只包含 2026 年 1 月的发票，而不是全部发票

边界情况：

• 导出超过 10,000 张发票：必须在 30 秒内完成，或显示进度指示
• 在移动端触发导出：下载到设备默认的下载位置

不在范围内： PDF 导出（故事 2）、定时导出（未来的史诗）

---

故事 2：把发票列表导出为 PDF

作为财务管理员， 我想要把我的发票历史导出为排版好的 PDF， 以便和会计分享一份专业的汇总。

[……验收标准按同样的模式……]

---

延伸材料

这个技能附带支持文件，可用时请使用：

• references/acceptance-criteria-craft.md：真正起把关作用的验收标准。在产出时应用它；它包含上面方法摘要压缩掉的校准和判断。
• templates/story-card.md：可填写的成果模板，质量关卡写在里面。当用户想自己完成文档而不是生成时提供。

评分量表（0 到 40）

交付前给这个技能的任何产出打分；32 分以上才算可以交付。

维度	0	5	10
用户视角与价值	故事从系统或开发者的角度写；"以便"缺失或循环（"以便更好用"）	角色具体，但部分"以便"描述的是功能而不是用户得到的结果	每个故事都点出具体的用户类型，"以便"写明他们获得的具体结果：干系人读了就知道为什么值得做
验收标准的可测试性与粒度	没有验收标准，或只是没有通过 / 不通过条件的文字描述	用了 Given / When / Then，但一条标准捆绑了多个行为，或测试的是界面方案而不是可观察的结果	每个可观察行为一条，每条都有明确的通过 / 不通过条件，测试结果而不是实现
非正常路径覆盖	只有正常路径：到处都没有空状态、错误或权限状态	列了一些边界情况，但关键失败模式（空状态、流程中途失败、权限边界）缺失或含糊	空状态、错误状态、权限边界和已知的技术约束都作为明确的验收标准或边界情况出现，并定义了行为
范围纪律与大小	故事有史诗那么大、相互依赖，没有"不在范围内"部分	有"不在范围内"，但很笼统；有些故事太大，无法估算或在一个迭代内独立交付	每个故事都能在一个迭代内完成、可以独立交付，拆分有记录的理由，"不在范围内"写明下一个故事从哪里开始

质量检查

• 每个故事都有具体的用户类型，而不是"一个用户"或"系统"
• "以便"解释了业务价值，而不只是功能描述
• 每条验收标准只测试一个可观察的结果，而不是一组行为
• 明确处理了空状态、错误状态和边界情况
• 写明了不在范围内的内容，而不是默认
• 故事相互独立：可以单独交付，不依赖未发布的工作（明确说明的除外）

反模式

• 不要从技术角度写用户故事：每个故事都必须从用户的视角出发，写明他们的目标
• 不要写无法测试的验收标准：每条标准都必须有清楚的通过 / 不通过条件
• 不要写一个迭代内完成不了的故事：把史诗拆成可估算、可独立交付的故事
• 不要省略边界情况：非正常路径和错误状态是必需的，不是可选的
• 不要跳过完成定义：没有它，"完成"对不同的人意味着不同的东西

示例触发语

• “根据这份说明为 [功能] 写用户故事”
• “把这部分 PRD 拆成带验收标准的用户故事”
• “把这些功能需求转成 Jira 任务”
• “为 [功能名称] 写用户故事和验收标准”
• “把这个史诗拆成可以进入迭代规划的独立故事”