0024 让分歧更早暴露：验收例子、方案确认点、两个方向的评审、反复的问题变成规则

• 状态：已采纳（补充 0012：评审的两个方向复用评审小组的机制；0022：方案确认点与闸口一样停下来等人，但在写代码之前）

背景

需求做出来"不符合预期"，多半不是代码写错，而是需求方和 agent 对"做成什么样"理解不同，并且直到验收才发现。到 1.8.0-beta.1 为止，需求方在确认需求说明之后，要等到报告才再看到结果；验收标准常常是抽象的描述（"在限制时间内重复发送会被拒绝"），测试的期望值由实现者自己定；代码评审一位评审者同时看"做没做对"和"做得规不规范"，后者常被挤掉；同一类规范问题在不同需求里反复被提出、反复修。

Matt Pocock 的 skills（grill-with-docs 的术语表、tdd 先写测试、code-review 分 Standards 和 Spec 两个方向、retro）、pstack 的 correct（把纠正变成规则）和 Specification by Example 的思路一致：把分歧放到最便宜的时候暴露，用具体的例子而不是抽象的描述对齐，把反复出现的问题交给机器挡住。

决定

• 验收标准带例子：acceptance-criteria 要求每条 AC 至少一组具体的输入和期望输出，按规则计算的给出覆盖边界的几组；确认前的独立审阅检查这一点，缺的替需求方拟好例子请其确认。方案的测试直接用这些例子作为期望值，不另编。
• 验收测试先提交：适合测试先行时，实现先把从例子写出的测试单独提交（失败的），在结果文件中写明文件和提交（acceptance_tests、acceptance_tests_commit）。代码评审前引擎用 git 核对它们之后有没有被改，改过的交给评审逐个确认依据。只核对、不阻止：测试本身写错是常见的合理修改。
• 方案确认点（designApproval）：方案审核通过、写代码之前，引擎可以停下来（状态 waiting_for_approval），请需求方看 preview.md（做完后会看到什么、需要确认的假设、不会变的）和界面原型（prototype/ 中的静态 HTML）。--approve 继续；要修改的走需求变更（更新 spec 后 --resume，从方案设计增量处理，再确认一次）。等待单独的 --resume 会被拒绝，避免对话误把"继续"当作确认。
  • 默认只对标准档的界面改动开启（mode: "ui"，由方案在结果文件中判断 ui_change）：界面最容易"做对了但不是想要的"，其他需求不增加等待。always 每次都停，off 关闭。
  • 无人值守的代价：等待提醒复用 waitingReminderHours；autoContinueHours 大于 0 时通过 Paseo 定时任务让对话在超时后按方案继续（默认 0，一直等待）。
  • 方案中的假设标明对使用者可见的影响（界面、数据、权限）。影响这些、猜错会做错的转为阻塞问题；其余在确认点请需求方过目，没有确认点时由报告交给需求方。
• 代码评审分两个方向（reviewAxes，默认标准档开启）：第一轮由规格评审（每条 AC 是否实现、测试期望值是否与例子一致、范围、与预览是否一致）和规范评审（项目惯例与范例文件、术语、测试质量、安全、简单性）并行，reviewer 核实汇总成一份结论。复用评审小组的并行和汇总，两位都用配置的 reviewer；配置了评审小组时以小组为准；后续轮次仍由一位评审核对修复。代价是每个标准档需求多两次评审。
• 术语表和范例文件：沿用仓库根目录的 GLOSSARY.md（不另建文件），增加"代码中的名字"；/req-setup 第一次整理并在项目说明中列出各类代码的范例文件；方案的每个任务写明参照的文件，新概念补进术语表。
• 反复出现的问题变成规则：完成报告把一条项目规则就能挡住的问题写进功能目录的 lessons.tsv。放在各自的功能目录，而不是一个共用文件，避免各需求分支合并时冲突。req digest 汇总所有工作区中的需求，同一类别出现在两个以上需求时提示；/req-retro 据此建议规则，落地后把类别写进 .requirement-pipeline/lessons-handled.txt。规则仍由人批准。

影响

• 状态文件新增可选字段 approval 和状态值 waiting_for_approval，格式版本仍为 1。回滚到更早的版本后，旧引擎把它当作可以继续的中断，继续时不经确认直接写代码，可以接受。
• 结果文件新增可选字段（ui_change、acceptance_tests、acceptance_tests_commit）。外部通知新增事件 approval。
• 标准档的界面改动多一次等待；每个标准档需求的第一轮代码评审多两次 agent 运行。都可以在配置中关闭。

本页由仓库中的 docs/adr/0024-confirm-early-review-axes.md 生成。在 GitHub 上编辑