AutoGPT 维护者 playbook 把仓库改成「Agent 协作合约」— AGENTS.md 如何替代 README

8 月 12 日 GitHub 发布 AutoGPT 维护者 playbook，AutoGPT 创始 AI 工程师 Nicholas Tindle 公开了一个 18 万星、约 150 个 open PR 的项目如何在「大部分 PR 由 Agent 生成」的现实下保持可维护性。

这不是一份「教你写 AGENTS.md」的教程，而是一份当 Agent 提交代码已经成为新常态时，开源仓库该怎么被重新设计的工作手册。

AutoGPT 的现状

• 180,000 stars
• 约 150 个 open PR，其中很大一部分由 Agent 写出
• AutoGPT 是这套指令文件的第三个版本——前两个版本分别是 CLAUDE.md 系列，被 Copilot 和 Codex 忽略，因为它们不认识 Claude 的私有文件名

核心思路用 Tindle 的话说：「It's basically somebody else paying for your compute」——如果一个贡献者想花 token 改进你的项目，让他花，但你必须把合约写在仓库里。

五道可组合的护栏

1. 一个标准指令文件，放在 Agent 看得到的位置

AutoGPT 中央统一在标准 AGENTS.md 上，原来分散的 CLAUDE.md 全部指向它。AGENTS.md 跟它管辖的代码放在同一目录，因为 Agent 读的是「眼前」的文件，不是 wiki 链接。

2. Skills 触发短语

一个 Skill 就是一个带 description 的指令文件，告诉 Agent 什么时候加载它。AutoGPT 在仓库里内置了一批：

• 前端工程师写了一个 Storybook-testing 指南，description 触发词是「组件在某些目录下」
• 后端同样规则以覆盖率阈值方式强制：80% 否则不开 PR
• PR 模板的措辞会触发一个测试 PR skill，让 Agent 安装 agent browser、启动应用、跑变更

结果是团队「几乎不再」收到跑不通的 PR。

3. PR 模板作为行为墙

不符合模板的 PR 会自动关闭，零犹豫。Tindle 说他先写了自动化，但后来发现根本不需要——Agent 在 bot 跑之前就已经自动遵守了模板。规则改变了行为，强制其实没机会执行。

4. CLA 作为人检测器

AutoGPT 的 CLA 签署要求「浏览器 + GitHub OAuth 流程 + 单独域名」——这是 Agent 不擅长的组合。一周未签署的 PR 关闭并邀请重新签署后重开。

Tindle 的建议是每个项目都应该这么做，包括 MIT 这种顶级项目。

5. Commit SHA 是 review 解决的前置条件

一些 Agent 会把所有 review thread 标记为 resolved 但不改代码。AutoGPT 的 pr-address skill 规定唯一合法序列：

fix → commit → push → reply → resolve

reply 必须链接修复 commit 的完整 SHA，从 git rev-parse HEAD 后取得。Skill 明确反模式：「Acknowledged」不是 fix，引用未触及被标记行的 commit 也不是。

关掉了什么

第一版「CI-failure 评论 Agent」把 Claude Code 接到 GitHub Actions，结果等于在 CI 里多了一个「广泛凭证」。Tindle 关掉了它——因为这意味着任何能跑 CI 的人，都能用同一个凭证访问 Claude Code 的所有能力。

这件事的真正重量

很多团队现在面对 Agent 提交 PR 的第一反应是「找更多 reviewer」或「写更严格的规则」。AutoGPT 的 playbook 反过来：不要试图说服 Agent 守规矩，而是把仓库改造成「不守规矩就进不来」。

这是一次结构性思维转换——

• 旧思路：教育 Agent 写更好的 PR → 治理 Agent 行为
• 新思路：把仓库规则变成 Agent 唯一能通过的入口 → 让治理成为产品本身

它解决了什么问题，没解决什么问题

解决了：

• Agent PR 质量参差不齐
• Reviewer 疲劳
• 规则执行不一致
• Backlog 堆积

没解决：

• Agent 之间的多智能体协作（这个 Anthropic 同一天的研究单独处理）
• Agent 提交的代码在长尾场景下的安全性
• 「谁对最终合并的代码负责」的归属问题

给其它项目的快速上手清单

如果你也想让自己的仓库进入「Agent 友好」状态，Tindle 给的清单可以浓缩成四步：

1. 写一份真正的 AGENTS.md，不是 vibe——列具体规则（允许路径、覆盖率门槛、PR 大小、commit 格式）
2. 把 AGENTS.md 从 CONTRIBUTING.md 里链出来，让人和 Agent 都看得到
3. 加 PR 模板 + 自动关闭 bot
4. 引入一个机器可解析的规则块（JSON）让 GitHub Actions 能直接读

整个流程大概 1 小时就能跑起来——大部分时间花在「哪些目录真的需要 CODEOWNERS gating」这种判断上，而不是配置本身。

这套东西的真正价值在于：当 90% 的 PR 都来自 Agent 时，仓库的可维护性不会取决于 Agent 的礼貌程度，而取决于仓库自身的合约设计。