4.6 KiB
优化方法（稳定核心）
减少"开发声称完成但复测不过"的循环成本。本文件是验收信号写法和三轮失败策略的 SSOT，其它文件引用这里。
三角色分工（Coordinator 编排 / Test 验证 / Developer 实现）见 roles-and-permissions.md；复测步骤、Coordinator 终检与环境对齐见 closed-loop.md。
1. 先把验收写成可观测信号（SSOT）
不要只写"页面可用""体验更好"。每个任务至少写三类信号：
| 类型 | 示例 |
|---|---|
| 可见文本 | 页面出现 确认应用标签、取消、将修改 |
| API 结果 | POST /api/... 返回 code=0 且字段存在 |
| 交互结果 | 点击按钮后出现确认区；取消后不触发写入 |
好的验收：
点击"预览变更"后，页面必须出现 API 返回的 diff 行：
- title
- 修改前值
- 修改后值
- coverChanged 提示
不好的验收：
预览功能正常。
2. 回报必须带证据，不带结论
Developer 的 worker_done 应报告：改了哪些文件、跑了哪些命令、自己如何复现验收路径、仍可能有的风险。Test 的复测报告同理：跑了哪些命令、命中/缺失了哪些验收信号、实际观察到什么、证据（snapshot / API 结果）。两者的"结论"都不作数，只有 Coordinator 落盘的 tasks.yaml 才是事实。
不要写：
已完成，应该可以了。
要写：
修改 web/app/fix/page.tsx。已运行 npm run build、go test ./...。
手测 /fix?fileId=1：搜索、选择候选、预览、确认区都可见。
风险：未执行真实写文件 apply。
3. 验证权在 Test，Coordinator 只信证据
即使 Developer 的 worker_done 写了"全部通过"，也必须由独立的 Test 复测（验证者 ≠ 实现者）。完整复测步骤与 worktree/服务对齐见 closed-loop.md。独立复测可避免三类假通过：测错服务实例、测到旧构建产物、开发只验证静态文本没验证真实交互。
Coordinator 不亲自复测，但要做终检：读 Test 的证据，确认它覆盖了每条验收信号且符合原始意图，避免"过了字面没过意图"。终检不通过就回写 failed_retest。
4. 三轮失败策略（SSOT）
每个任务最多自动派发三轮：
round 1: 常规修复
round 2: 带复测失败证据的定向修复
round 3: 明确指出重复失败点，要求 worker 自己复现完整路径
failed after round 3: 标记 leftover，继续下一个任务
三轮失败后不要继续消耗同一个 worker。常见原因：验收标准需要重新设计、Worker 对问题模型理解错了、UI 自动化与实际浏览器状态有差异、需要人工观察或调试工具介入。
留档字段（结构见 templates/tasks.schema.json）：
status: leftover
resolution:
leftoverReason: "failed after 3 supervised developer rounds"
dispatch:
rounds:
- round: 1
result: failed
evidence: "<why failed>"
- round: 2
result: failed
evidence: "<why failed>"
- round: 3
result: failed
evidence: "<why failed>"
5. 任务排序
- P0 阻塞主流程。
- P1 高频用户路径。
- P1/P2 体验改进。
- 重构和内部质量。
三轮失败的 P0 可以留档，但发布前需人工决策：降级范围、改验收标准、换新 Agent / 新 worktree 重做、人工修复。
6. 每轮派发只修一个明确问题
不要一次让 Developer Worker 修太多失败项，除非它们共享同一根因：
one dispatch = one bug = one acceptance path
优点：复测更快、失败原因更清楚、三轮失败留档更准确。
7. 把失败证据写给下一轮 worker
第二轮以后，派发 prompt 应突出"上一轮为什么没过"，而非重复原始描述。模板见 prompt-templates.md §「复测失败再派发模板」。
8. 优先让测试可执行化
如果某个问题需要多轮修复，说明它值得沉淀成自动化检查。这类可执行测试由 Test 拥有并维护（见 roles-and-permissions.md 权限表的 <integration_test_paths>）。优先级：
- API smoke。
- 浏览器脚本或 case 文档。
- 单元测试。
- 人工检查清单。
目标不是全部自动化，而是把最容易反复误判的路径自动化。
9. 结束条件
一轮闭环结束时，必须能回答：
- 哪些任务 verified？哪些 leftover？
- 每个 leftover 失败了几轮？最后一轮失败证据是什么？
- 当前工作树有哪些未提交改动？
- 是否还有 open / failed_retest 未处理？
答不清楚，闭环就还没结束。