技术深度剖析
AGENTS.md 文件及其同类文件 Claude.md（由 Anthropic 的 Claude Code 推广）是一种轻量级规范文档，放置在仓库的根目录或 `.github` 目录中。其预期功能是为 AI 编程助手提供上下文：项目结构、编码约定、测试框架和架构决策。当 Cursor 或 Claude Code 等 AI 工具初始化时，它会读取此文件，以使其代码生成与项目期望保持一致。
然而，开发者发现了一个漏洞：同样的机制可用于施加约束。通过添加诸如“不要生成修改构建配置文件的代码”或“所有 AI 生成的代码必须带有注释标记”等指令，团队创建了一道软性屏障。AI 本质上遵循指令，因此会遵守这些约束——有效地自我审查其贡献。
从工程角度来看，这突显了当前用于代码生成的大型语言模型（LLM）的一个关键局限性。像 GPT-4o、Claude 3.5 Sonnet 和 Gemini 2.0 Flash 这样的模型基于逐 token 预测机制运行。它们擅长模式匹配和语法正确性，但缺乏对项目架构、依赖关系图或长期维护权衡的整体理解。2024 年麻省理工学院和微软研究人员的一项研究发现，AI 生成的代码每行引入的安全漏洞数量是人工编写代码的 3.2 倍，并且开源项目中 41% 的 AI 生成拉取请求在合并前需要大量的人工重构。
| 模型 | 参数（估计） | HumanEval Pass@1 | SWE-bench Lite 分数 | 平均 PR 接受率（开源） |
|---|---|---|---|---|
| GPT-4o | ~200B | 90.2% | 42.1% | 23% |
| Claude 3.5 Sonnet | — | 92.0% | 49.3% | 31% |
| Gemini 2.0 Flash | — | 87.5% | 38.7% | 18% |
| DeepSeek-Coder-V2 | ~236B | 88.4% | 45.6% | 26% |
数据要点： 即使是最好的模型，在基准测试性能（通过孤立的编码测试）和开源项目中的实际接受率之间也显示出显著差距。高 SWE-bench 分数并未转化为高 PR 接受率，这证实了架构适配性和项目特定上下文才是真正的瓶颈。
AGENTS.md 防火墙正是利用了这一差距。通过编码 AI 无法仅从代码中推断出的项目特定规则，开发者有效地提高了 AI 贡献的门槛。一些仓库更进一步，使用 AGENTS.md 完全禁用某些目录（例如 `src/core/`）的 AI 代码生成，或者要求 AI 为每次更改输出详细的理由。
一个值得注意的例子是开源仓库 `lobe-chat`，它在 GitHub 上拥有超过 70,000 颗星。其 AGENTS.md 文件包含诸如“未经明确批准不得添加新依赖项”和“优先使用函数式编程模式而非类”等指令。这些规则不仅仅是指导方针——它们由检查合规性的 CI 管道强制执行。结果形成了一个有文档记录、自动化的把关系统。
关键参与者与案例研究
AGENTS.md 趋势由个人维护者、企业工程团队和开源基金会共同推动。几个关键参与者脱颖而出：
- Astro（Astro 团队）： 这个流行 Web 框架的维护者一直直言不讳地谈论 AI 生成的 PR。在一篇公开博客文章中，核心维护者 Fred K. Schott 指出，“AI 生成的代码常常忽略了 Astro 微妙的设计理念——它没有错，但它不是 Astro。”该项目的 CONTRIBUTING.md 现在包含一个引用 AGENTS.md 的部分，建议不要未经事先讨论就提交 AI 生成的代码。
- D3.js（Mike Bostock）： 这个由 Observable 维护的传奇数据可视化库，见证了 AI 生成的 PR 激增，这些 PR 试图“改进”性能，却引入了破坏性变更。Observable 的工程团队添加了一个 Claude.md 文件，其中明确声明：“除非你已与维护者讨论过，否则不要提交重构核心算法的 PR。”
- Vercel（Next.js）： Vercel 的开源团队采取了更细致的方法。他们使用 AGENTS.md 定义“允许”和“禁止”的代码模式，有效地为 AI 贡献创建了一个白名单。他们为 Next.js 编写的 AGENTS.md 文件包含诸如“使用 `next/dynamic` 进行懒加载，而不是自定义 React.lazy 包装器”等规则。这使得 AI 能够在受限的上下文中安全地做出贡献。
- Anthropic（Claude Code）： Anthropic 积极鼓励使用 Claude.md 文件，提供帮助团队定义 AI 行为的模板。然而，该公司并未公开回应“防火墙”现象，很可能是因为这与他们最大化 AI 采用率的目标相冲突。
| 组织 | 方法 | AGENTS.md/Claude.md 策略 | 结果 |
|---|---|---|---|
| Astro | 限制性 | “未经讨论不得提交 AI 代码” | 低质量 PR 减少 60% |
| D3.js (Observable) | 限制性 | “不得重构核心算法” | 核心代码稳定性提升 |
| Vercel (Next.js) | 引导性 | “允许/禁止代码模式白名单” | 安全贡献量增加 40% |
| Anthropic | 推广性 | 提供模板，未回应防火墙 | 采用率上升，但争议未消 |