给编码 Agent 写清交付验收条件
文章建议在仓库指引中要求 Agent 汇报类型检查、Lint 和相关测试结果,修 Bug 时先用失败用例复现。它还约束改动范围、重复失败后的停止条件,以及高风险操作的确认时机。
AI 深度解读
AI 编程助手改完代码就说「完成」,有时只是因为仓库没写清楚交付标准。作者分享了他们团队在 AGENTS.md 里试过的七条规则,覆盖测试证据、缺陷复现、改动范围、失败重试和操作权限,还给出了单文件测试命令。
对前端和全栈团队,最容易照搬的是把「跑过测试」变成一条可核对的交付记录。至于哪些检查该跑、失败几次该停,还得看仓库的实际工作流。
「完成」要拿什么来证明
作者把类型检查、Lint 和相关测试写进完成条件,还要求助手贴出运行摘要。这一条解决的是交付时怎么判断检查到底有没有跑。
Never claim "done" without running typecheck, lint and the relevant tests. Paste the summary of their output.
重点是最后一句。像 12 passed, 0 failed 这样的摘要让人能核对结果。团队在规则里同时写清测试范围,才能判断这 12 个用例有没有覆盖本次改动。
作者还给出了单文件命令 npx vitest run path/to/file.test.ts。对于使用 Vitest 的仓库,助手可以直接替换文件路径运行,省去猜脚本和参数的时间。测试跑红时,作者要求保留失败用例,禁止为了变绿而禁用、跳过或删除测试。新增 lint-ignore 或 type-ignore 注释也要说明理由。
修 Bug 先跑出同一个失败
作者要求先写一个能复现报告中问题的测试,再修代码,直到同一个测试通过。这条规则解决的是补丁改到了问题附近,却没碰到触发条件。
For bug fixes: first write a test that fails for the reported reason, then fix the code until it passes.
这一行里的 for the reported reason 最重要。比如报告说清空表单后仍能提交,测试就该在提交行为的断言处失败。如果它在初始化测试环境时就报错,后续跑绿也无法证明提交逻辑已经修好。
改动范围同样影响可核对性。作者举例,40 行差异容易审,400 行里混了 360 行空白改动,真正影响行为的代码就难找了。他们据此要求只动任务所需的文件,把纯格式调整和顺手重构留给独立改动。
命令反复失败时,什么时候该停
作者给同一命令设了 3 次失败的上限,达到上限就报告试过什么。原文举的是反复换着参数跑 npm install --force,耗掉十分钟和一批 token 的情形。这个上限适合拦住缺乏新线索的重试,每一次重试是否有依据仍要看报错。
另一条规则管操作权限。删除文件或分支、强制推送、运行迁移、发布和发消息之前,都要先询问。复核代码发生在改动之后,这些动作的确认点则在执行之前。
我的判断
我会优先采用两条规则,写明仓库里真实可用的命令,并要求交付时附上运行摘要。前者让助手知道该怎么验,后者让审阅者知道它验了什么。对于已经有 CI 的团队,可以让仓库规则负责本地快速反馈,让 CI 独立记录合并前的检查结果。聊天里的摘要由助手转述,CI 日志可以直接核对。
作者说这七条是他们测试中最能改变行为的,但原文没有给任务样本、各工具的版本、改规则前后的通过率,也没有逐条对照数据。现有结论属于经验之谈。Claude Code、Codex 和 Cursor 在具体仓库里会加载哪个规则文件、按什么顺序加载,原文也没交代清楚。至于 3 次上限,我会把它当作团队约定。安装故障和正在根据断言定位的代码错误,需要的判断不同。
能拿来做什么
- 把仓库实际可用的类型检查、Lint 和测试命令写进助手会读取的规则文件,同时约定交付时列出已执行的命令、输出摘要和受阻的检查。
- 维护 Vitest 项目时,补上单文件测试命令。修表单校验或 Node API 的回归时,先确认对应断言能失败,再用同一个用例验证补丁。
- 把重试和授权写成可执行的条件。同一命令第 3 次失败后,记录跑过的命令和最新报错。需要执行迁移、发布或强制推送时,先取得确认。