OpenAI 谷歌联手推出 AGENTS.md，能否成为编程 Agent 的「官方说明书」？

当 AI Agent 成为程序员的「第二大脑」，一个不大不小的问题也随之浮现：

我们该如何与这些越来越聪明的「数字同事」高效沟通？

Copilot, Devin, Claude Code, Gemini CLI, Codex…… 各家编程 Agent 打架都有自己的脾气。

开发者们为了让 AI 按自己的项目规范行事，不得不在代码库里塞进 .cursorrules, AGENT.md, CLAUDE.md 等五花八门的配置文件。

项目目录越来越臃肿，维护成本节节攀升。

正如一位开发者在 X (前 Twitter) 上所抱怨的：「这太疯狂了，我们到底在干什么？」

这张图精准地描绘了当前 AI 编程工具的现状：充满碎片化、各自为政，堪称「巴别塔」。

不过，这场混乱可能即将迎来终局。

OpenAI 和 Google 联手 AI 编程生态中的多个厂商，包括 Factory, Sourcegraph/Amp, Cursor 等，共同推出了一个简单、开放的新标准：

AGENTS.md

它的目标非常明确：用一个清晰、统一的文档，取代厂家特定的配置文件，为 AI 编程 Agent 提供一种可预测的方式来理解和操作软件项目。

换句话说，就是给 AI Agent 一本通用的 「项目说明书」。

这个小小的 .md 文件，究竟是解决 AI 协作难题的灵丹妙药，还是又一个「重复造轮子」的新麻烦？它能否真正统一 AI 编程的江湖，成为人类与 AI 协同编程新范式的关键基石？

今天，我们就来扒一扒 AGENTS.md 背后的故事、技术细节，以及它所引发的讨论。

README 是给人看的，AGENTS.md 是给 AI 看的

简单来说，AGENTS.md 就是一个 「给 Agent 看的 README.md」。

AGENTS.md 本身就是一个简单的 Markdown 文件，通常放置在代码仓库的根目录，与我们熟悉的 README.md 和 CONTRIBUTING.md 文件并存。

我们都知道，README.md 是写给人类开发者的，内容通常是项目简介、快速上手指南和贡献流程。但对于我们的「数字同事」—— AI 编程助手来说，这些信息远远不够。

它专门收录那些 人类开发者通常不关心，但 AI Agent 完成任务时却必不可少 的技术细节和操作指令。

AGENTS.md 的目标，就是将这些对人类贡献者来说可能过于冗长或无关紧要，但对 AI 却至关重要的上下文信息，统一收纳到一个专门的文件中。

官方给出的一个极简 AGENTS.md 示例如下：

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

可以看到，文件内容本身非常直白，就是一系列的指令和规则清单。这种设计的核心原则有三点：

1. 1. 位置固定：文件名和存放位置保持一致，方便 AI Agent 自动查找。
2. 2. 人机共读：格式轻量，人类和工具都能轻松阅读和解析。
3. 3. 灵活扩展：结构灵活，足以适应不同编程语言、框架，甚至是复杂的代码仓库。

想要使用 AGENTS.md 也很简单，只需要三步：

1. 1. 在代码仓库根目录下，创建一个名为 AGENTS.md 的文件。
2. 2. 在文件中添加能帮助 AI 高效工作的关键信息，包括但不限于项目概述、构建和测试命令、代码风格、测试说明、安全事项等。
3. 3. 添加其他额外指令，想象你有一个新入职的同事，你可以把所有想告诉他的事情都放进去。比如 Commit 信息的格式、Pull Request 指南、处理大型数据集的注意事项、部署步骤等等。

对于大型仓库，AGENTS.md 还支持 嵌套。你可以在重要的 package 中放置额外的 AGENTS.md 文件。Agent 在工作时，会自动读取离当前任务目录最近的那个文件，从而实现更精细化的指导。

据官方透露，OpenAI 自己的主代码库里，目前就包含了 88 个AGENTS.md 文件，可见其在复杂项目中的实用性。

社区讨论：是多此一举，还是确有必要？

AGENTS.md 一经提出，便在开发者社区引起了激烈争论。

争论一：AGENTS.md vs. CONTRIBUTING.md

最核心的争议便是：我们真的需要一个新文件吗？README.md 或 CONTRIBUTING.md 不够用吗？

反对声音：AI 的初衷与文档的统一

许多开发者认为，这似乎违背了 AI 的初衷。既然 LLM 的核心能力就是理解人类语言，那我们应该专注于优化给人类看的文档，让 AI 自行适应，而不是为 AI 单独「开小灶」。

这整件事本该在 CONTRIBUTING.md 里解决。AGENTS.md 里的内容，和人类贡献者想了解的东西没什么两样。

这种观点认为，AGENTS.md 的出现，不过是因为 人们长期忽视了为新开发者编写清晰的入门文档。

直到 AI Agent 的出现，这种文档的缺失才直接影响到了开发效率，于是大家才开始重视。本质上，这是一份迟到的 CONTRIBUTING.md。

支持理由：人与 AI 的本质差异

然而，支持者们给出了更具说服力的现实理由，核心在于：人类和 AI 的需求、理解方式和沟通模式存在根本差异。

1. 1. 写作风格和指令精确度：在 AGENTS.md 中，你可以用「ABSOLUTELY NEVER do sth.」（绝对不要做某事）这样直白甚至粗暴的指令来强调规则。AI 需要这种明确的、不带感情色彩的指令。但如果把这种话写在给人类同事看的文档里，可能会显得非常无礼。人类可以从委婉的建议中理解其重要性，但 AI 不能。
2. 2. 详略程度与上下文成本：给 Agent 的文档必须 高度精炼，因为过多的内容会消耗宝贵的 API token，增加成本，甚至降低输出质量。而给人类的内部工程文档，我们追求的是 100% 的完整性。AGENTS.md 就像一个经过优化的、专门喂给模型的精简数据集。
3. 3. 知识盲点不同：AI 和人类的知识盲点不同。比如，最新的模型可能已经对某个开源框架的 API 了如指掌，你无需在 AGENTS.md 里重复。但对于一个新入职的人类员工，这份 API 文档却是必读的。反之，项目中一些不成文的、只有团队成员才知道的「潜规则」，对 AI 来说就是完全的知识盲区，必须明确写出。

争论二：文件 vs. 文件夹，单体 vs. 结构化

另一大讨论方向，是关于 AGENTS.md 的组织形式。有经验的开发者提出，对于大型复杂项目，一个巨大的 Markdown 文件很快会变得难以维护。

对于复杂项目，「一个巨大的文件」可能不是最佳实践。许多开发者建议采用更有组织的文件夹结构，例如一个隐藏的 .agents 目录：

.agents/
├── index.md
├── auth.md
├── performance.md
├── code_quality.md
└── testing.md

这样做的好处显而易见：

• • 结构清晰：便于人类和 AI 维护。
• • 上下文精准：AI Agent 可以根据任务需要，只加载相关的 .md 文件，而不是把所有规则都塞进上下文，从而节省 token 并提高响应准确性。

争论三：根目录污染问题

这是一个困扰开发者社区多年的老问题。每当一个新工具或标准出现，都喜欢在项目根目录创建自己的文件，导致根目录越来越乱。

项目应该停止发明自己的根级文件和目录了。别再污染根目录了！

有开发者建议，应该遵循像 .well-known/ (RFC 8615) 或者 .config/ 这样的既有约定，将所有工具的配置和元数据都收敛到一个地方。这背后反映的是开发者对项目整洁性和规范性的追求。

争论四：继承还是覆盖？

AGENTS.md 支持在子目录中嵌套，但其规则是 「最近文件优先」。

有开发者指出了这其中的一个潜在风险：

子目录的上下文文件会 替换 (REPLACE) 而不是 增强 (augment) 上层的文件。我认为这种偏离是危险的，因为用户可能没有注意到这种差异。」

这意味着，如果你在子目录 apps/api/ 中放了一个 AGENTS.md，那么 Agent 在处理这个目录下的文件时，将 完全忽略 根目录的 AGENTS.md。这与许多开发者预期的「继承并覆盖」的行为模式不同，可能会导致意想不到的后果。

争论五：AI 是否应该更「聪明」？

还有一种观点认为，AGENTS.md 本身就是一个「过渡时期的产物」。

我们正处在一个过渡阶段，今天的智能体需要超越人类需求的特殊指导来理解代码库。但在不久的将来，我认为它们将不再需要。LLM 的全部魅力就在于它能阅读和理解我们的文字，我们应该在那个层面上为它设计。

这种观点认为，AI 的终极目标是理解人类的自然语言文档，而不是依赖为它特制的 agents.md。我们应该让 AI 去适应人类的沟通方式，而不是反过来。

意外收获：AI 正在倒逼规范文档协作

在所有的争论中，一个有趣的共识逐渐浮现：AGENTS.md 正在巧妙地「引诱」开发者们开始认真编写和维护文档。

过去，写文档常常被视为一项枯燥且回报周期长的工作。很多开发者懒得写，因为他们知道，没人会去读文档。

而现在，情况完全不同了。

正如一位开发者说：

（关于文档）我认为是人们懒得读文档，所以没人有动力去写。对于 Agent，我知道只要我把规则写进 CLAUDE.md 一次，它在一周内就会被上千个 Agent 实例读取。这才是编写文档的动力。

从这个角度来看，为人类写文档，投入产出比很低。但为 AI Agent 写文档，回报是即时且确定的——Agent 会 严格遵守 你的每一条指令。

这种 确定性的反馈，极大地激励了开发者去维护这份「机器说明书」。

当文档的价值能够通过 AI 助手的工作效率被即时、直观地展现出来时，编写高质量文档的动力就空前高涨了。这或许是 AGENTS.md 标准带来的最意想不到，也最有价值的「副作用」。

这有点像在诱导开发者养成维护良好文档的习惯。无论最终受益的是人类还是 AI，结果是好的。

更进一步：我们在为 AI 重塑数字世界吗？

跳出技术细节的争论，AGENTS.md 的出现，或许揭示了一个更宏大的趋势：为了更好地与 AI 协作，人类正在主动改造已有的信息结构，使其变得更「机器可读」。

一位开发者提出了一个类比：

我怀疑随着 AI 更多地融入社会，机器可读的实践将成为标准。一个很好的例子是自动驾驶和当地的法律/上下文。比如一个交通标志写着：『红灯禁止转弯。上学日早上 7 点到 9 点』。自动驾驶汽车需要知道：我在哪里？这个特定学校的上学日是哪几天？现在是什么日期和时间？……更现实的做法是，市政当局要么简化法律（减少上下文依赖），要么在标志上提供一些机器可读的信息（比如二维码）。

AGENTS.md 就是软件开发领域的那个「二维码」。

另一个例子则是之前兴起的 llms.txt，以 AI 友好的格式提供网页内容。

我们正在从一个默认「为人设计」的世界，慢慢过渡到一个「人机共生」的世界。在这个新世界里，信息不仅要让人类理解，也要让机器能够高效、准确地解析。

结语：迈向人机协同新范式的一小步

AGENTS.md 的诞生，是 AI 软件开发生态系统走向成熟和标准化的一个信号。

它试图解决一个普遍存在的痛点，通过一个简单、开放的方案，凝聚了行业主要参与者的共识。虽然它并不完美，也还没有得到所有关键厂商（尤其是 Anthropic）的全面支持。

但无论其最终形态如何演变，这场围绕 AGENTS.md 的讨论本身，已经极具价值。它促使我们深入思考：在一个人类工程师与 AI 智能体并肩作战的时代，我们应该如何构建新的沟通协议和协作规范？

当人类开始迎合机器的理解方式，这是无奈的妥协，还是进化的必然？

目前看来，AGENTS.md 是朝着一个更有序、更高效、更标准化的未来，迈出的坚实一步。

就像从口头语言到书面文字，再到今天的结构化数据，人类一直在发明新的工具和规范来更精确地传递信息。AGENTS.md 或许只是这条漫长道路上的一份「人机协作章程」。

它的未来，依赖于整个社区的共同建设。

你怎么看 AGENTS.md？你认为它是未来的方向，还是一个暂时的补丁？欢迎在评论区留下你的看法。