给AI编程代理开张验收单据，不然它说你代码没问题你都不敢信

现在AI写代码这事吧，代码能跑通只是第一步。真正的坑在于，代理说「我做完了」，你根本不知道它到底跑了哪些检查。它说测试通过，是全部通过还是跳过了一半？它说 lint 干净，是没跑还是真没报错？我最近受够了这种猜谜游戏。

ProofRun 这个工具解决的就是这个问题。它不判断你的代码对不对，它干的事有点像个公证人：用密码学方式证明，哪些检查确实跑了，在哪份代码上跑的，结果是什么。它就是一张验收单据，跑没跑、跑的结果如何，赖不掉。

我从零开始试了一遍，把步骤写下来。你不需要懂密码学，不需要懂深沉的东西，需要知道一点 git，会用终端就行。

先说环境。我用的是 macOS，Linux 应该同理，Windows 用 WSL 也行。需要装好的东西：Node.js 18 以上（用来跑 ProofRun）、git（代理跑完之后看改动记录用）、以及一个AI编程代理，比如 Claude Code 或者别的你手头在用的，都行。

第一步，把 ProofRun 装到你的项目里。在项目根目录打开终端，跑：

装完你会看到 node_modules 里多了东西，package.json 里多了一行依赖。这步一般不会出错，错了大概率是 Node 版本太旧，用 node -v 查一下，升到 18+ 再跑。

第二步，建配置文件。在项目根目录新建一个文件叫 .proofrun.json，里面写你想让代理在收工之前必须跑的检查。我这边写的是：

这个文件的作用就是告诉 ProofRun：以后代理跑完活，必须把这三样东西的原始输出交出来。type-check 是类型检查，就是让 TypeScript 编译器挑刺，看有没有类型写错的地方。lint 是代码风格检查，统一格式用。test 就是跑测试用例。

第三步，让 ProofRun 生成收据。跑这条命令：

正常的话你会看到终端里打印出三行结果，每个检查后面带一个类似 sha256:xxxxx 的字符串，那是校验和，可以理解为这堆输出内容的「指纹」。任何字符不一样，指纹就变，伪造不了。这时候项目里会多出一个文件，我这边叫 proofrun-receipt.json，里面存的就是刚才那串指纹和检查名。

踩坑提示：第一次跑的时候，我配置里的 lint 命令写错了路径，结果报了 ESLint couldn't find the config file。这个报错是我命令写错了，ProofRun 只是照实报出来。你得确保这几条命令在项目根目录单独跑也能通，再喂给 ProofRun。不然代理会因为检查失败而拿不到「验收单」，它会卡在那里重试，浪费名额。

第四步，让 AI 代理用上这个收据。这一步是关键。在项目里加一个文件叫 AGENTS.md（或者你用的代理读的其它名字，Claude Code 读这个），里面写一段规则：

意为：干完活必须跑 npx proofrun verify，拿到收据，并在最终的汇报里附带收据文件路径。这样代理就不会空口说白话。我之前遇到的情况是，代理一脸真诚地写「所有测试通过」，结果我手动一跑挂了 14 个用例。它偷懒了，默认跳过了一些耗时测试。加了这条规则之后，它至少得把证明跑完的文件摆在我面前。

第五步，也是我觉得最有用的一个用法：让代理跑完后把改动提交到 git，收据文件也一起提交。这样以后回看，能直接对着 commit 看到当时跑了哪些检查。跑：

然后在 git show 或者 PR 页面上，你能看到每次提交都带了一份收据，每个检查的原始输出和校验和都在。这比口头的「我测过了」强得多，也方便 code review 的时候不用浪费时间去问「这个改过吗」。

坑二：如果代理没有权限跑 npx proofrun，比如它用的是容器环境或者没装依赖，收据生成不了。我的解决办法是，在代理的权限配置里把 npx proofrun 加进白名单，让它能执行。不同代理的配置方式不一样，找「allowed commands」相关的设置就行。

坑三：代理可能会把收据文件内容改掉或者重新生成一个假的。这个其实防不住，因为代理手头有模型能力。不过这个工具设计上针对的是「无意漏跑」，「恶意伪造」是另一回事，要防后者得上更重的审计方案。对我这实验室场景，能证明「代理跑过且输出一致」就够了。

我用了大约一周，体感是：代码质量有没有变高不好说，但「不确定它到底测没测」的焦虑感确实少了。以前是它说完成我就信，现在我会先看一眼收据，确认三个检查都实打实跑过，再决定要不要人工复查。

有件事我得说清楚，ProofRun 不保证你的代码逻辑是对的，它证明的是「这些检查确实在这个版本的代码上跑过，结果是这样」。测试本身写得好不好，是另一回事。

学完这个，下一步可以试：把 proofrun verify 接到 CI 里，每次提交都强制生成收据，让验证变成硬性门槛而不是自觉。我在考虑这么弄，等跑顺手了再来写一篇。

---

本文编译自 Hacker News，原文：GitHub - yebiguo/ProofRun: A local verification receipt for AI coding agents · GitHub
版权归原作者所有，本文为基于公开报道的编译与独立分析。