write-acceptance

将工作交给他人验收

你已经完成了某项功能，而在它真正完成之前，必须有人亲眼看到它运行。对方对当前会话一无所知：不知道你做了哪些决定，不知道你已经检查过什么，也不知道屏幕上的五个按钮中哪一个是新增的。

docs/<feature>/ACCEPTANCE.md（位于项目的规划文件夹中，除非项目采用其他位置）是弥合这一信息差的页面。它只包含对方需要依次完成的检查清单，不包含其他内容。衡量标准是：对方能否从上到下完成所有步骤，不向你提一个问题；以及每个步骤是否都以一个对方确实能够检查的可观察结果结束。

了解读者是谁。 通常是用户，他们了解产品，但不了解本周完成的工作。有时是从未见过该功能的测试人员，不能假定他们知道任何内容在哪里。请按第二种情况来写：明确指出屏幕、菜单和按钮，不要写“常用位置”。用户可能猜得到的步骤，测试人员就可能会反馈无法继续。

这不是 write-handoff。 后者是将未完成的工作交给下一个 Agent——包括分支状态、要合并什么、从哪里继续。本文是将已完成的工作交给人来验收。一次执行可能两者都需要，而且两者毫无共通之处：读者不同，要回答的问题也不同。

应该写什么——以及绝不能写什么

只写机器无法完成的事项。 这是唯一的筛选标准，也是有人会照着执行的检查清单与被人扫一眼就放弃的清单之间的区别：

• 你没有凭据访问的控制台和账户——托管平台控制面板、DNS、应用商店、仓库密钥。
• 涉及实体设备或多台设备的情况——位于不同网络的两台机器、使用热点的手机、第二个用户、重启设备。
• 只有人眼才能判断的内容——新界面与相邻界面搭配是否合适、动画是否感觉卡顿、措辞是否妥当。
• 任何你无法在此运行的内容——你无法为其构建的平台、需要硬件的测试套件、尚未安装的资源。请清楚说明这一点，并写明它能够验证什么。
• 唯一一个能够证明该功能确实存在的演示，即使你已经通过测试验证过——对方还是希望亲眼看它运行一次。

绝不要要求对方重复你已经做过的事。 测试套件、格式化工具，以及 EXECUTION.md 中所有已通过的项目——这些都是你的工作，而且已经完成。在这里重复它们，会掩盖那三个确实需要人来完成的步骤。如果有任何失败项，那也不属于验收步骤；它是一个缺陷，应由你修复，或记录为暂缓事项，写入问题日志（放在项目用于记录未决问题的位置；如果项目没有约定，就在计划旁边添加问题章节或文件）。

如何编写

先说明哪些内容已经完成并经过验证，并指向 EXECUTION.md，然后说明还剩下什么，以及为什么需要有人亲自处理（控制台、第二台设备、亲眼查看）。接着列出检查清单。

• 分成有序的章节，方便读者做完一节就停下，每节标注大致耗时——## A. Provision (console work, ~30 min plus DNS propagation)。 只有二十分钟的人也应该能看出哪些内容来得及完成。
• 每条命令都应能直接复制粘贴，并注明运行位置——在哪台机器、哪个控制台、哪个 shell 中运行。使用围栏代码块，填写实际值而非占位符；只有他们才能提供的值除外（说明这些值是什么，以及从哪里获取）。
• 说明哪些可观察结果才算证据，而不是凭感觉判断。“同步完成不算证据，转发路径才算。”“systemctl is-enabled docker 必须输出：enabled。”成功标准是“应该能用”的步骤，无法用于反馈结果。
• 指出哪些看起来像是坏了，其实并没有。 例如，默认拒绝访问的关卡、刻意不设置的恢复邮箱、需要十分钟才能完成的首次运行——在读者遇到这些情况的地方说明“这是有意设计的，并非故障”，不要把说明放在脚注里。
• 详细操作方法指向运行手册，而不是在此重述。 本页列出预期完成的事项及顺序；运维文档或用户指南说明具体操作方法。同一流程写两遍，内容迟早会不一致。
• 说明你希望对方反馈什么：需要报告哪些步骤、需要提交哪些文件、还有哪些待确认的问题。若未解决的问题不影响检查清单，明确说明这一点。
• 为刚睡醒的人写作。 使用朴素的句子和产品术语，不要用运行过程中的阶段 ID 或简写。如果某一步是因为你在他们不在时做出的决定而存在，用一个分句说明。

在确保诚实的前提下，尽量简短。如果工作确实只需看一眼，文件就用三行说明，并指出要打开的那一项——凭空设计一套仪式，比简短写明要做什么更糟。

验收部分

结尾列出编号检查项——计划中用户自己的使用场景，将其改写为实际要执行的操作，而不是要作出的断言。每项都要说明：要设置什么、要做什么，以及用于判定完成的确切可观察结果。这些检查项用于确认工作是否完成，因此必须放在页面末尾并编号，这样读者就能回复“D.2 通过了，D.3 显示了 X”。

如果后续一轮工作在早先的验收内容上新增了验收项，请追加一个新章节，而不是改写旧内容——他们可能已经按旧内容操作过。

放置位置

• 将文件写入 docs/<feature>/ACCEPTANCE.md，并在最后一个阶段一并提交。
• 在 EXECUTION.md 中添加指向该文件的链接（“剩余验收内容见 ACCEPTANCE.md 中的检查清单”），并在结项报告中添加链接；结项报告只保留摘要——检查清单应放在这里，而不是发在很快就会被刷走的聊天消息里。
• 后续运行新增或完成步骤时，直接更新此文件。 close-roadmap 和 close-plan 会在确认任何内容已完成前逐项检查此文件，然后将其归档——将仍有必要重跑的内容移入该功能的当前测试计划。任何无人反馈的检查项都会阻碍结项，因此检查清单要短到足以让人逐项完成。