可验证用户故事:从用户价值到可反驳的完成条件
用户故事用一条短句表达某类主体在某个场景中的目标与价值。它不是需求的全部,也不是开发任务。可验证用户故事必须同时连接问题证据、业务规则、示例、验收条件和发布观察,使团队能判断实现是否真的满足目标。
一、故事句式的准确边界
常见句式是:作为某类主体,我希望完成某个目标,从而得到某种价值。三个部分分别回答“谁在什么上下文中行动”“需要达成什么结果”“为什么值得做”。句式是组织对话的工具,不是 Scrum 的强制字段,也不能替代流程、状态、权限和非功能约束。
1. 主体不是泛化的“用户”
主体应当影响规则或结果。例如“组织管理员”和“受邀成员”在邀请功能中拥有不同权限、可见信息和失败恢复。如果两类人行为完全相同,就不必为了格式虚构角色。
主体不能只写人口属性。年龄或职业只有在确实改变场景和约束时才有意义。B2B 产品常用责任、权限和数据关系定义主体,例如“拥有成员管理权限的工作区管理员”。
2. 目标描述可观察结果
“点击邀请按钮”是界面操作,“成功邀请尚未加入组织的成员”才是目标。实现可能从按钮改为批量导入或 API,用户目标仍然成立。
目标也不能无限宽。一个故事若同时包含注册、审核、付款和通知,无法在一次评审中建立清晰完成条件,应按独立价值与状态边界拆分。
3. 价值说明结果为何重要
“为了提升体验”无法验证。价值可连接时间、错误、风险、收入或任务成功,例如“减少管理员逐个录入账号的时间”。价值假设需要发布指标验证,验收测试只能证明功能行为,不证明市场效果。
二、可验证性的五层证据链
flowchart LR
P["问题证据"] --> S["用户故事"]
S --> R["业务规则"]
R --> E["具体示例"]
E --> A["验收测试"]
A --> O["发布观察"]2
3
4
5
6
问题证据证明值得解决;故事确定主体、目标和价值;规则说明允许与禁止;示例把抽象规则放入具体数据;验收测试判断实现;发布观察检验价值假设。任意一层缺失都会产生不同风险。
| 层 | 典型输入 | 可验证输出 | 不能替代 |
|---|---|---|---|
| 问题证据 | 日志、工单、任务数据 | 基线、受影响主体、频率 | 实现验收 |
| 用户故事 | 场景与目标 | 可讨论的价值切片 | 完整规则 |
| 业务规则 | 权限、状态、计算 | 决策表、不变量 | 具体示例 |
| 示例 | 确切前置与输入 | 预期可观察结果 | 全部边界集合 |
| 验收测试 | 示例与接口 | 通过/失败证据 | 发布价值 |
| 发布观察 | 指标定义与窗口 | 效果、护栏、回滚判断 | 单次测试 |
三、写故事前先确定分析单位
一条故事应围绕一个主体能够独立感知的结果。拆分时使用以下判断:
- 结果能否独立发布或隐藏在 feature flag 后。
- 是否有独立的成功和失败状态。
- 是否能在不依赖另一半未完成逻辑时验收。
- 是否改变不同主体或资源的权限。
- 是否需要不同的风险、性能或数据约束。
按技术层拆成“前端故事、接口故事、数据库故事”通常不产生独立用户价值。这些是实现任务,应挂在同一价值故事下。按 CRUD 动词拆分也不总正确:创建草稿与正式提交若有不同状态和价值可以拆;仅把一个表单切成“打开、填写、点击”则不能独立验收。
四、从业务规则生成验收维度
故事确定范围后,列出会改变结果的维度:
- 主体:管理员、普通成员、外部协作者、匿名访问者。
- 资源关系:自己的、同组织的、其他组织的、已删除的。
- 对象状态:草稿、活动、暂停、归档、处理中。
- 输入类别:合法、缺失、重复、超限、格式错误。
- 时间:有效期内、边界时刻、过期、时区变化。
- 并发:重复提交、旧版本、乱序回调。
- 依赖:正常、超时、限流、部分失败。
维度组合可能很大,不需要穷举笛卡尔积。先覆盖每条业务规则的正例、反例和关键交叉条件;安全、金额、不可逆操作和数据丢失风险需要更强覆盖。
五、INVEST 作为评审启发式
INVEST 常用于检查故事是否 Independent、Negotiable、Valuable、Estimable、Small、Testable。它是启发式,不是自然定律,也不要求故事完全没有依赖。
| 项目 | 实际检查 | 失败信号 | 修正 |
|---|---|---|---|
| Independent | 能否独立排序和验收 | 必须等待无关功能 | 按价值路径或接口契约解耦 |
| Negotiable | 是否保留实现讨论空间 | 故事直接指定按钮颜色和库 | 把必要约束与实现建议分开 |
| Valuable | 主体能否感知结果 | 只有重构动作 | 关联用户/业务结果或改为技术工作项 |
| Estimable | 规则和未知是否足够明确 | 关键依赖未验证 | 建立 spike 或补证据 |
| Small | 是否能在反馈周期内完成 | 横跨多个流程终态 | 按规则、主体或状态拆分 |
| Testable | 是否有可观察结果 | “更方便”“优化体验” | 写具体示例和阈值 |
六、完整案例一:邀请成员
输入事实
工作区管理员当前只能逐个创建账号。过去四周共发起 1,280 次邀请,其中 11% 因邮箱已属于当前工作区而失败,6% 因邀请已存在而重复操作。安全规则要求只有具备 members.invite 能力的主体可邀请。
故事
作为拥有成员邀请权限的工作区管理员,我希望一次提交多个邮箱并在发送前看到逐项预检结果,从而减少重复操作,同时避免向已有成员或未授权域发送邀请。
业务规则
- 服务端对每次请求重新校验主体能力和工作区关系。
- 邮箱规范化后在本次输入中去重。
- 已是成员的地址不发送邀请,返回
already_member。 - 已有未过期邀请的地址返回
pending_invitation。 - 组织启用域白名单时,白名单外地址返回
domain_not_allowed。 - 单次最多 100 个唯一地址;超过上限不做部分发送。
- 发送使用批次幂等键;同一键重复提交返回原批次。
示例矩阵
| 权限 | 输入 | 现有关系 | 预检结果 | 提交结果 |
|---|---|---|---|---|
| 有 | a@example.com | 无 | 可邀请 | 发送一封 |
| 有 | a@example.com, A@example.com | 无 | 规范化后一个地址 | 发送一封 |
| 有 | member@example.com | 已是成员 | already_member | 不发送 |
| 有 | pending@example.com | 邀请有效 | pending_invitation | 不重复发送 |
| 无 | 任意合法邮箱 | 无 | 不暴露成员关系 | 403 |
| 有 | 101 个唯一邮箱 | 无 | batch_too_large | 整批不发送 |
可观察验收
预检返回每个规范化地址的稳定 result code;界面将 code 映射为文案。无权限请求只返回统一拒绝,不泄露某邮箱是否为成员。提交成功返回 batchId、accepted 与 rejected 计数。使用同一幂等键重复请求时 batchId 与计数不变。
失败注入
让邮件供应商在第 20 个地址后超时。批次记录每项投递状态,重试只处理未确认项;UI 显示处理中而不是整批成功。若无法确认供应商是否接收,状态为 unknown 并通过回调或查询对账。
发布验证
主指标是每个成功受邀成员对应的管理员操作次数;护栏包括误邀请撤销率、无权限拒绝率、邮件投诉率和批次部分失败率。验收测试通过不代表指标一定改善。
七、完整案例二:保存筛选器
分析人员每周重复配置订单状态、地区和日期范围。筛选可含个人可见字段,分享时必须重新做字段级权限。
故事:作为经常分析订单的运营人员,我希望保存一组命名筛选并在之后恢复,从而减少重复配置;在分享筛选时,接收者只能看到自己有权访问的条件和结果。
拆分决定
“保存个人筛选”与“分享筛选”分成两条故事。保存只影响当前主体,分享新增资源授权、所有者、撤销和字段脱敏,失败边界不同。
保存故事的验收
- 名称 trim 后 1–60 个字符,同一主体下重名返回可修正冲突。
- 保存的是规范化筛选 schema 和 schemaVersion,不保存当前结果列表。
- 已删除字段在恢复时标记 unsupported,不静默改变查询。
- 两个标签页基于同一 version 编辑时,旧版本保存返回 409。
- 删除筛选后直接打开旧 URL 返回明确不存在并提供返回列表。
分享故事的验收
分享链接引用稳定 shareId,不在 URL 写完整筛选。服务端每次访问校验 share 状态、接收者、字段能力和租户。所有者撤销后既有链接立即拒绝。接收者无权使用的条件不能仅在前端隐藏。
失败分支
当 schema 从 v2 升级到 v3,迁移器无法识别旧自定义运算符。恢复结果进入 needs_attention,展示无法应用的条件;不能丢弃该条件后直接查询,因为结果语义已改变。
八、故事、验收条件与 Definition of Done
验收条件属于具体 backlog item,描述该功能在何种条件下可接受。Definition of Done 是团队或产品增量共享的质量标准,例如代码评审、自动化测试、安全扫描、可观测性和发布准备。
每条故事重复“通过 CI、完成评审”会制造噪音;若某故事有额外安全审计或数据迁移要求,应写成该故事专属验收或交付约束。
九、故事变更与可追踪性
故事不是签字后冻结的合同。新证据出现时可拆分或改写,但要保留决策链:问题证据、故事 ID、规则版本、场景、测试、发布 flag 和指标。
需求修改后执行影响分析:哪些 Gherkin 场景失效、接口错误码是否变化、分析事件是否仍能计算指标、旧客户端如何处理新增状态。只改故事文本而不改下游工件,会产生表面一致。
十、常见不可验证写法
| 写法 | 问题 | 修正 |
|---|---|---|
| 作为用户,我想要更好的邀请体验 | 主体、结果和尺度都不清 | 指定管理员、批量预检和减少重复操作 |
| 支持批量邀请 | 只有功能名 | 补主体、规则、失败和价值 |
| 页面响应要快 | 无采样点和阈值 | 指定设备、网络、p75/p95 与交互 |
| 用户可以管理筛选 | 包含创建、编辑、删除、分享多条链路 | 按价值与授权边界拆分 |
| 所有异常正确提示 | 异常集合未知 | 列出错误分类、可恢复动作和泄露边界 |
十一、评审与调试
评审时让产品、设计、开发和测试各自根据故事写出三个具体示例。如果示例对主体、输入或结果理解不同,先修正规则,不急于估算。
线上出现争议时从失败请求关联回场景:主体能力、资源关系、输入类别、对象状态、规则版本和实际输出。若现有故事无法判断该组合,新增规则与示例,而不是只修一个页面分支。
十二、综合练习
为“批量导出订单”编写两条独立故事:发起导出和取得结果。覆盖字段权限、数据量上限、异步状态、过期下载、重复发起和部分字段不可用。
验收标准
- [ ] 每条故事只有一个可独立感知的结果。
- [ ] 主体由权限或责任定义,不写泛化用户。
- [ ] 业务规则都有正例、反例和可观察输出。
- [ ] 安全边界由服务端验证且不泄露资源存在性。
- [ ] 失败注入包含超时、重复、旧版本和部分失败。
- [ ] 发布指标与验收测试分开,并定义护栏和观察窗口。
来源
- Cucumber:Gherkin Reference(访问日期:2026-07-18)
- The Scrum Guide 2020(访问日期:2026-07-18)
- OWASP Authorization Cheat Sheet(访问日期:2026-07-18)
- RFC 2119:Requirement Levels(访问日期:2026-07-18)