AutoGPT 如何用 AGENTS.md 和技能门控管理 AI 生成的拉取请求
Your contributors are AI-first now. Is your project?
AutoGPT 维护者发现，AI 智能体不会主动阅读文档，因此将指令放在 AGENTS.md 和技能文件中，并置于代码目录旁。他们通过强制 PR 模板、测试计划、CI 覆盖率门槛和 CLA 签名等门控机制，将智能体提交的 PR 从“不可用”转变为“可用但不符合路线图”。其中 CLA 签名因需浏览器和 OAuth 流程，被用作区分人类与智能体的“人类探测器”。
AutoGPT 的经验指出发现机制比文档完善度关键，agent 只读当前目录层级的指令，所以把 AGENTS.md 放在代码旁比继续写 wiki 更有效。
在维护者的对话中，同一个问题反复出现：当 pull request 队列里塞满了由智能体编写的代码时，你该怎么办？
这也是 AutoGPT 创始 AI 工程师 Nicholas Tindle 每天都要面对的事情。我在五月与他交流过，那是为了维护者月活动。采访当时，AutoGPT 拥有超过 180,000 个 star 和大约 150 个待处理的 pull request。其中很大一部分 pull request 是由智能体编写的，包括 Copilot、OpenClaw 以及 AutoGPT 自己的内部工具等。我交谈过的大多数维护者都有同样的反应：关上门。关闭 pull request。不要让团队背负审查垃圾代码的负担。
Nicholas 看到了积极的一面：
这基本上就是别人在替你付算力钱。
Nicholas Tindle, founding AI engineer at AutoGPT
在他看来，如果贡献者愿意花自己的 token 来改进你的项目，那就让他们去做。只要确保进门的方式只有一种，那就是适合你的方式。
你的文档不是问题所在。可发现性才是。
AutoGPT 先尝试了最显而易见的做法。更好的贡献者指南。更好的文档。一个专门用于该仓库协作的完整 wiki。
这些都没有带来任何改变。事实证明，除非你明确告诉这些工具去读你的文档，否则它们不会去读。这就是我们很多人搞错的地方。我们对待文档的方式，就好像智能体会自己去找它一样。它不会。智能体只读摆在它面前的东西，也就是它所在目录层级的内容。
于是 AutoGPT 开始把指令放到智能体会查看的位置。首先是 CLAUDE.md 文件，因为 Claude 在生成 pull request 时缺乏足够的仓库专属上下文。提交信息尾注让每一个都容易被识别，因为它们会在提交信息尾注中自我标明。接着他们撞上了下一堵墙：Copilot 和 Codex 会忽略 Claude 文件，因为它们不是 Claude。于是他们把标准 AGENTS.md 集中管理，并让 Claude 文件指向它。
下面是我觉得最有用的一个细微之处。AGENTS.md 的作用域限定在一个目录内。而技能可以在该目录之外被发现。（如果你还没发布过技能：技能就是一个指令文件，带有一段描述，告诉智能体何时加载它。智能体会预先扫描这些描述，当任务匹配时再拉入完整的指令。）
AutoGPT 的 AGENTS.md 就放在它所管理的代码旁边。这个位置本身和指令内容同样重要。
如果你在写后端测试，同时又想着要做前端相关的事情，某个技能可能会被动态加载。它不会知道该去哪个目录找 AGENTS.md 文件，但技能可以告诉它。
他们的前端工程师受够了同一类坏掉的 pull request，于是写了一份指南，并作为技能发布在仓库里。描述中包含了触发措辞：如果你的组件位于这些文件夹中，就写一个 Storybook 测试。现在每一个接触该仓库的测试框架都会自动发现它。后端也以同样的方式强制执行自己版本的规则：覆盖率达不到 80% 就别提 pull request。
真正有效的关卡
这些就是你可以为自己的项目调整采用的关卡。
大声地强制执行 pull request 模板。AutoGPT 会告诉智能体，不符合模板的 pull request 会被毫不犹豫地自动关闭。他们真的构建了执行这一点的工具，然后发现根本不需要运行它。在 AutoGPT，这条规则在自动化真正运行之前就已经改变了智能体的行为。智能体们遵守了模板。人类贡献者有时需要更多空间，Nicholas 把这视为一项特性：
如果你不遵守模板，我知道你大概率是个人类，我会对你更宽容一些。
测试计划的小把戏。模板要求填写测试计划，而其中的措辞不经意间提到了要测试该 pull request。这句话触发了一个名为 test PR 的技能，它会（在获得许可的情况下）安装智能体浏览器，启动应用，并执行该改动。智能体本是为了勾选一个复选框，结果却运行起了代码。
他们几乎再也收不到无法正常工作的 pull request 了。现在他们收到的是能正常工作但不符合路线图的 pull request，而这是一个好得多的问题。
把 CI 变成一堵墙，而不是一个建议。Codecov 覆盖率阈值是必需的检查项。智能体打开 pull request，几分钟后回来查看，发现无法合并，于是加载测试技能，编写测试。没有人需要开口要求。
把 CLA 当作人类检测器。 AutoGPT 采用双许可证，但 Nicholas 主张每个项目都应该这样做，包括 MIT 许可的项目。签署需要浏览器以及在独立域名上走 GitHub OAuth 流程。智能体目前在这方面表现很差，而且理由充分：大多数维护者不希望一个智能体在浏览器中登录 GitHub 并拥有广泛的账户访问权限。
如果你的 CLA 在一周后仍未签署，我们就关闭该拉取请求，并附上一条评论说明请签署 CLA，完成后重新打开。
这道关卡之所以有效，是因为它把人类重新拉回了流程中。CLA 是一种选择。行为准则复选框也能起到同样的作用。
在解决审查线程之前要求提供 commit SHA。 有些智能体会在不触碰代码的情况下把每个审查线程都标记为已解决。AutoGPT 的解决办法是在仓库中放置一个 pr-address 技能，声明唯一有效的顺序：修复、提交、推送、回复，然后解决。回复必须链接到修复所用的提交，并在提交后从 git rev-parse HEAD 中提取完整的 SHA，这样智能体就无法复用旧的 SHA。该技能甚至列出了反模式：“已确认”不算修复，引用一个并未触及被标记行的提交同样不算。
他们关掉的那道关卡
当某项检查失败时，AutoGPT 会让一个智能体读取运行结果并评论出了什么问题。他们的第一个版本把 Claude Code 接入 GitHub Actions，并在工作流内部对其进行身份验证，这意味着 CI 中又多了一个拥有广泛权限的凭证。在工作流中运行 Copilot 则无需这样做就能得到相同的结果。Nicholas 对此很推崇：
真是难以置信。我很高兴自己再也不必为 YAML 费心了。我再也不会为 action 写 workflow 了。
后来他们还是把评论功能关掉了。他们的 CI 经常失败，而一个整天播报每次失败的机器人，并不比失败本身好多少。教训在于克制：保留能减轻维护者负担的东西，关掉会变成噪音的东西。
四个值得写下来的坑
一个糟糕的 AGENTS.md 文件比没有 AGENTS.md 更糟。AutoGPT 起初到处乱放这些文件，结果污染了上下文，把智能体的注意力拉向无关紧要的文件。如果行为变差了，就去读读你写的东西。
GraphQL API 会对你限流。当团队里每个工具都以个人用户身份访问 CLI 时，你很快就会触到上限。创建一个 GitHub App，并通过它来认证 CLI。
重量级的审查工具是要花真金白银的。他们的 pull request 测试装置会克隆分支、启动八个各司其职的智能体、运行整个技术栈，并上传截图。这很棒。但它也贵到他们现在只对非常小或非常大的 pull request 运行它。
去审计你已授权的应用。AutoGPT 是 Secure Open Source Fund 的一部分，而这是 Nicholas 从这项工作中得出的心得之一。他们试用后又放弃的每一个工具都留下了一项授权。
如果你不再使用某个 GitHub 应用，就把它从已授权应用中移除。在这次直播之后，现在就做一次小小的审查，去看看你都授权了什么。你会大吃一惊的。
用 GitHub 登录如今已经如此自然而然，以至于我们大多数人从未回头去看过。我在直播期间打开了我的设置。他说得没错。
并非一切都是门槛
Nicholas 带来的两点收获几乎与工具无关。
第一：你不必接受每一个 pull request。合并别人 LLM 的输出是不对称的。你要永远承担维护工作。关闭这个 pull request 并自己动手构建修复，是一个正当的选择。
你可以完全禁用 pull request。你可以将 issue 创建限制为协作者。Nicholas 把这些控制手段与他在这场访谈中反复回到的那件事联系起来：维护者需要可调节的旋钮。有时候正确的答案是更少的随手提交的 pull request。有时候是只接受 issue。有时候是“先和我们谈谈”。
SQLite 不接受外部代码贡献。他们接受 bug 报告。这是一个正当的开源边界。你的项目也可以有自己的边界。
第二：当你关闭一个 pull request 时，你要重建自己，如果合理的话，把贡献者添加为共同作者。AutoGPT 大约有 800 名贡献者，所以再多一个对他们来说毫无成本。对大多数人来说，重要的是他们的问题得到了修复，并且有人注意到他们来过。
我要带回去的东西
开源一直是通过让协作变得明确而演进的。许可证让权限变得明确。Issue 让工作变得可见。Pull request 让审查成为一种共享实践。仓库中的指令看起来是这一方向上的又一步，不过我会对此持保留态度。还没有人找到正确的形态。AutoGPT 已经到第三版了，而它是通过先发布糟糕的版本、观察智能体如何使用它们才走到这一步的。
你仍然决定什么该被纳入。你仍然设定标准。区别在于，更多的这种判断可以放在代码旁边，也就是你的贡献者和他们的智能体已经在的地方。
去看看 AutoGPT 仓库，读一读他们是如何组织自己的智能体文件的。
然后去加入 maintainers.github.com。因为我在那里工作，我无论如何都会这么告诉你，所以还是听听 Nicholas 怎么说吧：
你必须去那里。你必须注册。它能让你在 GitHub 上获得你想要的所有人脉。那就是我学到所有这些内容的地方，也是我分享这些内容的地方。
这里也是 Tiny Wins 被优先处理的地方，即每周持续推出由维护者提出的小型改进。其中一些需求已经出现在 GitHub 在 Maintainer Month 期间重点介绍的控制项中。这里也是我们的产品经理和工程师在任何东西发布之前阅读反馈的地方。如果你想对平台接下来为维护者提供什么功能拥有发言权，那就是这个渠道。你的贡献者已经是以 AI 为先了。在下一个 pull request 到来之前，把规则放到代码旁边。
来源：GitHub Blog · github.blog