Skip to content

可验证用户故事:从用户价值到可反驳的完成条件 ​

用户故事用一条短句表达某类主体在某个场景中的目标与价值。它不是需求的全部,也不是开发任务。可验证用户故事必须同时连接问题证据、业务规则、示例、验收条件和发布观察,使团队能判断实现是否真的满足目标。

一、故事句式的准确边界 ​

常见句式是:作为某类主体,我希望完成某个目标,从而得到某种价值。三个部分分别回答“谁在什么上下文中行动”“需要达成什么结果”“为什么值得做”。句式是组织对话的工具,不是 Scrum 的强制字段,也不能替代流程、状态、权限和非功能约束。

1. 主体不是泛化的“用户” ​

主体应当影响规则或结果。例如“组织管理员”和“受邀成员”在邀请功能中拥有不同权限、可见信息和失败恢复。如果两类人行为完全相同,就不必为了格式虚构角色。

主体不能只写人口属性。年龄或职业只有在确实改变场景和约束时才有意义。B2B 产品常用责任、权限和数据关系定义主体,例如“拥有成员管理权限的工作区管理员”。

2. 目标描述可观察结果 ​

“点击邀请按钮”是界面操作,“成功邀请尚未加入组织的成员”才是目标。实现可能从按钮改为批量导入或 API,用户目标仍然成立。

目标也不能无限宽。一个故事若同时包含注册、审核、付款和通知,无法在一次评审中建立清晰完成条件,应按独立价值与状态边界拆分。

3. 价值说明结果为何重要 ​

“为了提升体验”无法验证。价值可连接时间、错误、风险、收入或任务成功,例如“减少管理员逐个录入账号的时间”。价值假设需要发布指标验证,验收测试只能证明功能行为,不证明市场效果。

二、可验证性的五层证据链 ​

mermaid
flowchart LR
    P["问题证据"] --> S["用户故事"]
    S --> R["业务规则"]
    R --> E["具体示例"]
    E --> A["验收测试"]
    A --> O["发布观察"]

问题证据证明值得解决;故事确定主体、目标和价值;规则说明允许与禁止;示例把抽象规则放入具体数据;验收测试判断实现;发布观察检验价值假设。任意一层缺失都会产生不同风险。

层典型输入可验证输出不能替代
问题证据日志、工单、任务数据基线、受影响主体、频率实现验收
用户故事场景与目标可讨论的价值切片完整规则
业务规则权限、状态、计算决策表、不变量具体示例
示例确切前置与输入预期可观察结果全部边界集合
验收测试示例与接口通过/失败证据发布价值
发布观察指标定义与窗口效果、护栏、回滚判断单次测试

三、写故事前先确定分析单位 ​

一条故事应围绕一个主体能够独立感知的结果。拆分时使用以下判断:

  1. 结果能否独立发布或隐藏在 feature flag 后。
  2. 是否有独立的成功和失败状态。
  3. 是否能在不依赖另一半未完成逻辑时验收。
  4. 是否改变不同主体或资源的权限。
  5. 是否需要不同的风险、性能或数据约束。

按技术层拆成“前端故事、接口故事、数据库故事”通常不产生独立用户价值。这些是实现任务,应挂在同一价值故事下。按 CRUD 动词拆分也不总正确:创建草稿与正式提交若有不同状态和价值可以拆;仅把一个表单切成“打开、填写、点击”则不能独立验收。

四、从业务规则生成验收维度 ​

故事确定范围后,列出会改变结果的维度:

  • 主体:管理员、普通成员、外部协作者、匿名访问者。
  • 资源关系:自己的、同组织的、其他组织的、已删除的。
  • 对象状态:草稿、活动、暂停、归档、处理中。
  • 输入类别:合法、缺失、重复、超限、格式错误。
  • 时间:有效期内、边界时刻、过期、时区变化。
  • 并发:重复提交、旧版本、乱序回调。
  • 依赖:正常、超时、限流、部分失败。

维度组合可能很大,不需要穷举笛卡尔积。先覆盖每条业务规则的正例、反例和关键交叉条件;安全、金额、不可逆操作和数据丢失风险需要更强覆盖。

五、INVEST 作为评审启发式 ​

INVEST 常用于检查故事是否 Independent、Negotiable、Valuable、Estimable、Small、Testable。它是启发式,不是自然定律,也不要求故事完全没有依赖。

项目实际检查失败信号修正
Independent能否独立排序和验收必须等待无关功能按价值路径或接口契约解耦
Negotiable是否保留实现讨论空间故事直接指定按钮颜色和库把必要约束与实现建议分开
Valuable主体能否感知结果只有重构动作关联用户/业务结果或改为技术工作项
Estimable规则和未知是否足够明确关键依赖未验证建立 spike 或补证据
Small是否能在反馈周期内完成横跨多个流程终态按规则、主体或状态拆分
Testable是否有可观察结果“更方便”“优化体验”写具体示例和阈值

六、完整案例一:邀请成员 ​

输入事实 ​

工作区管理员当前只能逐个创建账号。过去四周共发起 1,280 次邀请,其中 11% 因邮箱已属于当前工作区而失败,6% 因邀请已存在而重复操作。安全规则要求只有具备 members.invite 能力的主体可邀请。

故事 ​

作为拥有成员邀请权限的工作区管理员,我希望一次提交多个邮箱并在发送前看到逐项预检结果,从而减少重复操作,同时避免向已有成员或未授权域发送邀请。

业务规则 ​

  1. 服务端对每次请求重新校验主体能力和工作区关系。
  2. 邮箱规范化后在本次输入中去重。
  3. 已是成员的地址不发送邀请,返回 already_member。
  4. 已有未过期邀请的地址返回 pending_invitation。
  5. 组织启用域白名单时,白名单外地址返回 domain_not_allowed。
  6. 单次最多 100 个唯一地址;超过上限不做部分发送。
  7. 发送使用批次幂等键;同一键重复提交返回原批次。

示例矩阵 ​

权限输入现有关系预检结果提交结果
有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 与交互
用户可以管理筛选包含创建、编辑、删除、分享多条链路按价值与授权边界拆分
所有异常正确提示异常集合未知列出错误分类、可恢复动作和泄露边界

十一、评审与调试 ​

评审时让产品、设计、开发和测试各自根据故事写出三个具体示例。如果示例对主体、输入或结果理解不同,先修正规则,不急于估算。

线上出现争议时从失败请求关联回场景:主体能力、资源关系、输入类别、对象状态、规则版本和实际输出。若现有故事无法判断该组合,新增规则与示例,而不是只修一个页面分支。

十二、综合练习 ​

为“批量导出订单”编写两条独立故事:发起导出和取得结果。覆盖字段权限、数据量上限、异步状态、过期下载、重复发起和部分字段不可用。

验收标准 ​

  • [ ] 每条故事只有一个可独立感知的结果。
  • [ ] 主体由权限或责任定义,不写泛化用户。
  • [ ] 业务规则都有正例、反例和可观察输出。
  • [ ] 安全边界由服务端验证且不泄露资源存在性。
  • [ ] 失败注入包含超时、重复、旧版本和部分失败。
  • [ ] 发布指标与验收测试分开,并定义护栏和观察窗口。

来源 ​

从前端走向软件产品工程的长期路线图。