AutoGPT 如何用 AGENTS.md 和技能门控管理 AI 生成的拉取请求

维护者们的讨论中反复出现同一个问题：当拉取请求队列里堆满了由 AI 智能体编写的代码时，你该怎么办？

这也是 Nicholas Tindle 每天都要面对的事情，他是 AutoGPT 的创始 AI 工程师。我在五月的维护者月活动中采访了他。采访当时，AutoGPT 拥有超过 18 万颗星和大约 150 个未关闭的拉取请求。其中很大一部分拉取请求是由智能体编写的，包括 Copilot、OpenClaw 以及 AutoGPT 自己的内部工具等。我接触过的大多数维护者都有同样的反应：关门大吉。关闭拉取请求功能。不要让团队耗费精力去审查这些垃圾代码。

但 Nicholas 看到了其中的好处：

这基本上就是别人在替你付算力费用。

Nicholas Tindle, founding AI engineer at AutoGPT

在他看来，如果贡献者愿意花自己的 token 来改进你的项目，那就让他们去做。只要确保进入项目的唯一途径是符合你需求的方式就行。

你的文档不是问题所在。可发现性才是。

AutoGPT 一开始尝试了最显而易见的做法：更好的贡献者指南、更好的文档，甚至建了一个完整的 wiki 专门介绍如何与该代码仓库协作。

但这些都没有带来任何改观。事实证明，除非被明确告知，否则这些工具不会主动去读你的文档。这正是我们很多人搞错的地方。我们以为把文档写好了，智能体就会自己去找来看。但它不会。智能体只会读取眼前的东西，也就是它们当前工作目录层级下的内容。

于是 AutoGPT 开始把指令放到智能体会看的地方。首先是 CLAUDE.md 文件，因为当时 Claude 生成的拉取请求缺乏足够的仓库特定上下文。提交尾注让每个这样的请求都很容易被识别出来，因为它们会在提交尾注中表明自己的身份。接着他们遇到了下一堵墙：Copilot 和 Codex 会忽略 Claude 文件，因为它们不是 Claude。所以他们把标准统一到了 AGENTS.md，并让 Claude 文件指向它。

我发现最有用的一个细节是：AGENTS.md 的作用范围限定在某个目录内。而技能（skill）可以在该目录之外被发现。（如果你还没发布过技能：技能就是一个带描述的指令文件，描述会告诉智能体何时加载它。智能体会预先扫描描述，当任务匹配时再拉取完整的指令内容。）

AutoGPT 的 AGENTS.md 文件就放在它所管辖的代码旁边。这个位置本身，和文件里的指令内容一样重要。

如果你在写后端测试，却突然想到要做前端的事情，某个技能可能会动态加载。它不会自己知道该去哪个目录找 AGENTS.md 文件，但技能可以告诉它去哪里找。

他们的前端工程师厌倦了同一类有问题的拉取请求，于是写了一份指南，并把它作为技能发布在代码仓库里。技能描述中包含触发语：如果你的组件位于这些文件夹中，就编写一个 Storybook 测试。现在，凡是接触到这个仓库的智能体工具都会自动发现这条规则。后端也以同样的方式强制执行自己的规则版本：测试覆盖率达不到 80%，就不许开拉取请求。

真正有效的关卡

以下这些关卡，你可以根据自己项目的实际情况进行调整。

高调执行拉取请求模板。AutoGPT 会告诉智能体，不符合模板的拉取请求会被毫不犹豫地自动关闭。他们构建了真正能执行此操作的工具，结果发现根本不需要运行它。在 AutoGPT，这条规则在自动化工具运行之前就已经改变了智能体的行为。智能体都遵守了模板。而人类贡献者有时需要更多灵活空间，Nicholas 把这看作一个特性：

如果你不按模板来，我就知道你可能是个真人，我会对你更客气一些。

测试计划的小技巧。模板要求填写测试计划，而模板的措辞会顺带提到“测试这个拉取请求”。这句话会触发一个名为 test PR 的技能，该技能会（在获得许可的情况下）安装 agent browser，启动应用，并执行这次改动。智能体本来只是想勾选一个复选框，结果却把代码跑了起来。

他们现在几乎不会再收到跑不起来的拉取请求了。现在收到的是能跑、但不符合路线图的拉取请求，这算是个好得多的麻烦。

把 CI 变成一堵墙，而不是一个建议。Codecov 的覆盖率阈值是必检项。智能体打开拉取请求，几分钟后再回来看一眼，发现无法合并，于是加载测试技能，开始编写测试。整个过程不需要任何人去吩咐。

把 CLA 当作“人类检测器”来用。AutoGPT 采用双重许可，但 Nicholas 认为每个项目都应该这么做，MIT 许可也不例外。签署 CLA 需要浏览器，并且要在独立域名上走一遍 GitHub OAuth 流程。智能体目前很难完成这件事，而且这也有充分理由：大多数维护者并不希望智能体以浏览器方式登录 GitHub，并拥有广泛的账户访问权限。

如果一周后 CLA 仍未签署，我们会关闭该拉取请求，并附上一条评论：签署 CLA，完成后重新打开。

这道关卡之所以有效，是因为它把人类重新拉回了流程中。CLA 只是其中一种方案，行为准则勾选框也能起到同样的作用。

在解决评审讨论串之前，要求提供提交 SHA。有些智能体会在不改动任何代码的情况下，把所有评审讨论串都标记为“已解决”。AutoGPT 的解决办法是在仓库里放一个 `pr-address` 技能，明确规定唯一合法的操作顺序：修复、提交、推送、回复，然后解决。回复必须链接到修复所用的提交，并在提交后通过 `git rev-parse HEAD` 获取完整 SHA，这样智能体就无法复用旧提交。该技能甚至点名了反模式：“已确认”不算修复，引用一个并未改动被标记代码行的提交同样不算。

他们关掉的那道关卡

当某项检查失败时，AutoGPT 曾让智能体去读取运行日志，并评论哪里出了问题。他们的第一个版本把 Claude Code 接入了 GitHub Actions，并在工作流内部完成认证，这意味着 CI 里又多了一个权限过宽的凭据。在工作流中运行 Copilot 也能达到同样效果，却无需引入这个凭据。Nicholas 对此赞不绝口：

这太不可思议了。我太高兴了，再也不用碰 YAML 了。我再也不会为某个 action 编写工作流了。

不过他们最终还是把评论功能关掉了。他们的 CI 失败频率很高，一个机器人整天对每次失败都做解说，并不比失败本身好到哪里去。这里的教训在于克制：保留能降低维护者负担的东西，关掉那些只会变成噪音的功能。

四个值得记下来的坑

一份糟糕的 AGENTS.md 比没有 AGENTS.md 更糟。AutoGPT 一开始到处放这种文件，结果污染了上下文，把智能体的注意力引向了无关紧要的文件。如果行为变差了，回去读读你自己写的东西。

GraphQL API 会对你进行速率限制。当你团队中的每个工具都以个人用户身份调用 CLI 时，很快就会触及上限。请创建一个 GitHub App，并通过它来认证 CLI。

重量级的审查工具成本不菲。他们的拉取请求测试装置会克隆分支，启动八个承担不同任务的智能体，运行整个技术栈，并上传截图。这很棒，但成本也高到他们现在只对非常小或非常大的拉取请求运行它。

去审计一下你授权的应用。AutoGPT 是安全开源基金（Secure Open Source Fund）的一部分，而这是 Nicholas 从该项工作中得出的心得之一。他们试用过又弃用的每个工具，都留下了一个授权。

如果你停止使用某个 GitHub 应用，请将其从已授权应用中移除。看完这场直播后，现在就做个小审计，去看看你都有哪些授权。你会大吃一惊的。

用 GitHub 登录如今已如此自动化，以至于我们大多数人从未回头查看过。我在直播期间打开了我的设置。他说得没错。

并非所有东西都是一道关卡

Nicholas 的两个心得几乎与工具无关。

第一：你不必接受每一个拉取请求。合并别人的大语言模型输出是不对等的。你要永远承担后续维护工作。关闭拉取请求并自己动手修复，是一个合理的选择。

你可以完全禁用拉取请求。你可以将问题创建权限限制为仅限协作者。Nicholas 将这些控制措施与他采访中反复提到的那个观点联系了起来：维护者需要旋钮。有时正确的答案是减少路过式拉取请求。有时只保留问题反馈。有时是“先跟我们聊聊”。

SQLite 不接受外部代码贡献。他们接受 bug 报告。这是一个合理的开源边界。你的项目也可以有这样一个边界。

第二：当你关闭一个准备自己重建的拉取请求时，如果合理的话，把贡献者添加为共同作者。AutoGPT 大约有 800 名贡献者，所以多一个对他们来说毫无成本。对大多数人而言，重要的是他们的问题得到了修复，并且有人注意到他们来过。

我要带回去的东西

开源一直通过让协作变得明确而不断演进。许可证让许可变得明确。Issue 让工作变得可见。Pull Request 让代码审查成为共同实践。仓库中的说明文件看起来是朝着这个方向的又一步，不过我对这一点持保留态度。目前还没有人找到正确的形态。AutoGPT 已经迭代到第三个版本，而它之所以走到这一步，是因为先发布了有缺陷的版本，然后观察智能体如何利用它们。

你仍然决定什么该纳入。你仍然设定标准。不同之处在于，更多的判断可以放在代码旁边，而你的贡献者及其智能体本来就已经在那里了。

去看看 AutoGPT 仓库，读一读他们是如何组织智能体文件的。

然后去加入 maintainers.github.com。反正我也会这么建议你，因为我在这里工作，所以不如让 Nicholas 来说：

你必须去那里。你必须注册。它能让你在 GitHub 获得你想要的所有人脉。我就是在那里学到这些东西的，也是在那里分享它们的。

同样是在那里，Tiny Wins 会获得优先处理——那是每周持续推送的一批由维护者提出的小型改进需求。其中一些请求已经出现在 GitHub 在维护者月期间重点展示的控制功能里了。我们的产品经理和工程师也是在那里阅读反馈，然后才让任何功能上线。如果你想对平台下一步为维护者做什么有发言权，那个地方就是你的舞台。你的贡献者已经是 AI 优先的了。在下一个 pull request 落地之前，把规则放到代码旁边吧。