write-user-story

编写用户故事

用户故事结构

每个故事都按顺序包含三个核心部分：目的／概述、需求／范围和验收标准。根据实际交付内容选择辅助部分，而不是照搬模板。根据请求和现有上下文判断工作类型；只有在尚未明确的区别会实质性改变故事时，才提出有针对性的问题。

目的／概述说明预期结果及其价值。需求／范围包含功能、约定、交付物和约束条件。验收标准列出足以验证是否完成的最少数量的独立条件。技术使能工作以及发现／策略工作不需要虚构终端用户角色。

模板

除非有充分理由添加辅助部分，否则此骨架就是完整的故事。

## Purpose/Overview

[Outcome, value, and relevant context.]

## Requirements/Scope

1. [Required capability, contract, or deliverable, including binding constraints.]

## Acceptance Criteria

[Distinct verifiable completion conditions.
Use Given-When-Then for behavior or a concise checklist for contracts/deliverables.]

验收标准

对于可观察的行为，使用 Given-When-Then；对于技术约定或决策交付物，若简洁且可验证的检查清单表达得更清楚，则使用检查清单。每条标准都对应已商定范围内一个独立的完成条件。涵盖重要的错误和边界行为，但不要把每个配置字段都扩展为单独的场景。验收标准没有目标数量：不要为了简短而删掉重要条件，也不要把验收标准写成测试计划。每个 Given/When/Then/And 都必须作为单独的项目符号行（- Given ...、- When ...、- Then ...），不能作为单个项目符号下的缩进行续行——标准 Markdown 会将软换行的续行合并为一整行，渲染成 “Given abc When xyz Then 123”，而不是预期的分步格式。

适合任务的验证方式

工作	必需行为
面向用户／运行时的更改	如果在验收标准之外还有帮助，则添加 Testing Guidance。对于实际的 UI 工作流，适合使用包含简短步骤和预期结果的 Manual Testing。
后端／API／库更改	有用时，添加 Controlled Verification：约定检查、本地测试框架、桩，或受控故障条件。可以说明自动化验证的级别，无需编写测试。绝不要要求破坏共享或生产部署，也不要要求等待真实故障发生。
纯发现／策略／决策工作	不添加运行时 Testing Guidance。通过需求和验收标准验证决策材料、权衡、建议、约束条件以及商定的评审。不要写 Testing Guidance: N/A。

混合型工作应根据实际请求的内容，采用适合的方式逐项验证：“策略”一词本身并不意味着可以省略对确实要求的运行时更改进行测试。

不要在故事中加入测试代码、模拟配置、夹具脚本和实现计划级别的测试用例。这是为了限制细节，并不意味着不能说明自动化验证或约定验证。

条件性部分

仅在满足条件时添加相应部分。

• 范围之外 — 仅当需要排除对本次请求的一种合理但不同的解读，或用户明确提出了边界时添加。相邻主题、未来增强功能和无关功能都不是添加排除项的理由。
• 非功能性需求 — 具体且重要的安全性、兼容性、并发性、完整性或性能约束。不要为了让模板看起来完整而添加泛泛的愿望。
• 补充说明 — 仅包含相关且不具约束力的上下文。影响正确性或验收的承诺属于需求；若可验证，也应纳入验收标准——绝不能只放在说明中。
• 技术方案 — 可选的高层次背景。不要虚构实现，也不要仅仅因为某项技术约束属于技术内容就将已商定的约束删掉。
• 相关链接 — 每个保留的链接都必须有明确用途：依赖项、先前行为、上级范围、规范或证据。不要罗列所有相邻的 Jira 项目键，也不要虚构关联关系。

编写指南

角色格式（适用于用户角色）

As a [user persona/role]
I want [goal/desire]
So that [benefit/value]

涉及真实用户角色时使用此格式。对于技术赋能或决策事项，直接说明结果及其价值，而不是虚构用户角色。

INVEST 原则

• Independent — 可独立交付
• Negotiable — 细节可调整
• Valuable — 能带来明确价值
• Estimable — 团队能够估算工作量
• Small — 可在一个冲刺内完成
• Testable — 具有明确的验证标准

最佳实践

应做事项 ✓

1. 说明价值和结果，无论受益者是谁
2. 制定具体且可验证的验收标准
3. 涵盖重要的错误场景和边界情况
4. 将约束性要求放在 Requirements 中
5. 统一领域术语
6. 说明每个关联工单的作用

不应做事项 ✗

1. 不要为技术工作或决策工作虚构最终用户角色
2. 不要含糊其辞——“提升性能”需要有指标
3. 不要省略验收标准
4. 不要添加交付内容不需要的章节
5. 不要为从未纳入范围的相邻主题添加“范围外”
6. 不要在故事中加入测试代码、测试夹具或详细的测试设置
7. 不要过度规定实现方式——具体“如何实现”由开发人员决定
8. 不要将约束性要求放在 Additional Notes 中

快速参考清单

• 目的清楚说明了价值和背景
• 所选章节与实际交付内容相符
• Requirements 具体明确，且包含所有约束性要求
• 验收标准彼此独立、可验证，且符合交付物类型
• 涵盖了重要的错误和边界情况
• 验证方式符合工作类型；对于决策工作，则应正确地省略验证
• 每个已添加的可选章节都发挥了实际作用
• 说明了每个关联工单与当前工单的关系
• 故事的规模适合在一个冲刺内完成
• 仅在需要时概述技术方案，且不过度规定实现方式
• 仅在非功能性需求较重要时才将其纳入

缺少可选章节并不代表存在缺陷。

如需深入了解各章节的编写指南，请参阅 references/section-details.md。 如需查看常见问题及修改前后的示例，请参阅 references/pitfalls.md。 如需查看完整的故事示例，请参阅 references/example.md。 如需了解 JIRA 标记转换，请参阅 references/jira.md。