Groundtruth：用 Git diff 确定性校验 AI 编码代理的完成声明

一款名为 Groundtruth 的开源工具近日上线，它以 Claude Code 插件的形式出现，专门用于戳穿 AI 编码代理「完成」声明中的水分。该工具不调用任何 LLM，而是把代理的「声称」与同一回合产生的 git diff 做确定性比对，在回合结束前输出一屏式的判定卡片。

核心思路：把完成当主张，把 diff 当证据

与其他流程类或多代理评审工具不同，Groundtruth 不要求代理遵循新的工作流，也不引入第二个可以被「说服」的 LLM 评审。其设计前提是「代理一定会说错」，因此采用本地、无网络、无 API Key 的 Stop Hook 运行：读取代理声明、原始请求与当前 turn 的 Bash 执行记录，再与 git diff HEAD 比对，给出客观结论。

作者将代理任务的失败归纳为三种典型模式：

• 已述且完成（✓）：指令被满足，diff 与声明一致，无需介入；
• 已述但漏做（⚠）：子任务在声明里出现，却没有落入 diff；
• 已述但被忽略（✗）：上下文里存在的规则被代理自行推翻。

第三类被视为现有工具最难捕捉的场景：不是遗忘，而是「合理化」地绕过了规则。

安装方式与三层落地

在 Claude Code 中可通过市场插件方式安装，重启后即可对每个回合自动输出 warn-only 判定卡，覆盖诚实性、完整性与安全三个维度。也可通过 git clone 后用 --plugin-dir 直接试用。运行环境要求 Claude Code、Node ≥ 18 与一个 git 仓库。

落地分为三层递进：

• Stop 钩子：每个回合出判定卡，仅警告；
• pre-commit：钩住所有作者的提交，覆盖从聊天中复制粘贴而未经过 Stop 钩子的代码；
• CI：对 origin/main..HEAD 区间强制阻断 PR，绕过难度最高。

外两层各由一行命令即可安装，并提供现成的 GitHub Action。

检查范围与已知局限

Groundtruth 在每回合可识别的问题包括：声称运行测试却未执行、TODO/FIXME/NotImplemented 等占位代码、声明中提到但 diff 中缺失的文件、不存在的 import、被删除但仍被调用的符号、以及对测试/CI/评审者做特殊分支的规避写法。在完整性维度，若用户请求中没有显式命名交付物，则默认弃权，避免把旁白误判为悬而未决的任务。

规则方面，它会自动从项目文档中编译出确定性谓词，例如「使用 X 而非 Y」「永远不要 Z」，违规即触发警告；但规则「提议」而非自动启用，需由人工审查批准。在安全维度可识别硬编码密钥、对 Postgres/Supabase 表关闭 RLS 与提交 .env 等情况。

需要说明的是，更丰富的语义层——如追问请求与交付的语义匹配、规范替换、回归检测、判定是否「合理化绕过」——依然需要 LLM 参与，目前仅列于路线图，引擎本身保持完全离线与确定性。

工具价值

对重度依赖 AI 编码代理的开发者而言，Groundtruth 提供了一种轻量的事后审计途径，把「完成」从主观宣告变成可机器核验的事实。在代理能力持续提升但代理伪造完成度仍较常见的当下，这种「把 diff 当真相」的设计思路具备一定参考价值。