编码 Agent 的完成声明需要哪些证据

Agent 说「Done」，究竟是在说代码改完了，还是权限合规、审查完成、用户需求也得到满足了？原文作者认为，这些结论需要不同的证据，不能靠一个绿色勾选统一担保。

作者维护的 Agent Role Contracts（ARC）只检查其中一小块：声明里的角色和权限范围是否冲突。它的价值在于边界明确。对使用 AI 编程的团队，这篇文章更值得带走的是：怎样把一句含糊的「完成」，拆成可以检查、可以继续推进的状态。

测试通过，为什么还不能直接叫完成

原文用一个修改校验逻辑的任务举例：Agent 获准写入 src/**，随后修改代码、报告测试通过，并宣布完成。看起来流程已经闭环，但还有三个问题。

第一，工作是否被允许？给执行者声明 src/** 写入范围，并不等于运行时真的限制了工具的写入权限。说明书上的权限和实际生效的权限，需要分别检查。

第二，要求的工作是否确实发生？计划里写着独立审查，不能证明有人审过最终版本。即使发生过审查，也还要确认被审查的版本，就是最终合并的版本。

第三，结果是否满足需求？本地测试通过，能提供关于被测代码的证据，却不能自动证明功能在用户实际使用的环境中正常。

测试通过是一项证据，不能替代权限、审查和实际效果的全部证据。

这不是否定测试，而是限制测试结论的适用范围。把几个不同的问题塞进一个完成状态，后续接手的人就得自己补查。

ARC 演示的能力，为什么刻意做得很窄

作者维护的 ARC 是一个开源检查器，检查声明中的 Agent 角色、范围、审查和交接安排。

它的 quickstart 可以用 Git、Node.js 22.5+ 和 npm 运行。下面的命令用于复现声明检查：

git clone https://github.com/suirindo/agent-role-contracts.git
npm --prefix agent-role-contracts run demo --silent

注意第二行运行的是仓库的 demo，不是启动 Agent 执行代码修改。

这个演示的预期顺序是 PASS → expected FAIL → PASS。它读取虚构的 JSON 声明，不启动 Agent，也不写入目标文件。中间那次预期失败，只证明一个很具体的性质：请求的操作范围与声明的授权范围冲突，检查器能够拒绝它。

反过来，声明检查得到 PASS，也不能证明执行者身份真实、文件系统权限已经生效、独立审查实际发生，更不代表执行获得授权。这些控制需要宿主系统提供。

因此，ARC 更适合作为任务派发前的一道声明检查。它能提前发现配置上的矛盾，但不能代替执行时的权限控制和执行后的验收。

我的判断

我认同作者对完成状态的拆分。对于 AI 编程，状态描述越具体，接手的人越容易决定下一步。比如：

「实现已完成，本地测试已通过；独立审查待完成；生产环境行为尚未检查。」

这句话比「Done」更有操作价值，因为它交代了已有证据和剩余工作。

但原文没有给出生产事故、团队对照实验，或引入 ARC 前后的效果数据。演示也是合成声明检查。因此，关于这种拆分能降低多少风险、是否值得增加一个工具，目前只能视为设计主张，不能当成已验证的收益。

常见替代做法是在 CI、身份与访问管理（IAM）、运行时权限及审查流程里分别控制这些环节，作者也认可这条路。已有流程能覆盖需求的团队，可以先改善完成报告；只有声明经常冲突、任务派发容易越界时，才有必要评估额外的声明检查。

验收强度也不必一刀切。原文提出应考虑操作的副作用，但没有给出具体分级标准，团队仍需自己制定。

能拿来做什么

• 给前端或 Node 任务的完成报告增加明确状态，分别写出实现情况、已执行的验证，以及尚未完成的审查或环境检查。
• 给 Agent 配置 src/** 等写入范围时，同时确认工具运行时如何落实限制，避免把提示词里的约定当成文件系统权限。
• 要求独立审查的任务，应记录被审查版本的明确标识，并核对它与最终合并版本是否一致。
• 根据任务副作用设置验收要求。内部小改动可以讨论是否以测试通过为门槛；涉及用户实际体验的改动，应明确还需要什么环境中的行为检查。