什么是 AGENTS.md？如何为 Claude Code、Codex、Cursor 及其他 AI 编程代理创建它

如果你最近在现有代码库上启动过 Claude Code、Cursor 或 Codex，很可能在项目根目录中遇到过一个名为AGENTS.md的文件，并好奇是谁把它放在那里的。它不是README。它不是给团队看的文档。它是一组专门为即将开始编辑你代码的AI 代理编写的指令。

我一度忽略了这些文件，以为它们只是炒作。然后我目睹 Codex 在一个已经用了两年 pnpm 的客户端项目上运行了npm install。它删除了锁文件，然后愉快地发起了一个拉取请求。这正是AGENTS.md存在要防止的问题。花 10 分钟写一个，代理就不会在每次会话中重复犯同样的错误了。

以下是关于它你需要知道的一切。

什么是 AGENTS.md？

AGENTS.md是一个纯Markdown 文件，你把它放在仓库根目录，用来告诉 AI 编程代理你的项目是如何工作的。你可以把它想象成一份写给机器而不是人看的README。它包含构建命令、测试命令、编码约定以及代理无法仅通过阅读你的源代码就能猜到的硬性规则。

该标准的制定者将其描述为一个可预测的、专用的位置，用于为编码代理提供它们所需的上下文。你的README涵盖的是面向人类的内容，比如快速入门、徽章和贡献说明。AGENTS.md涵盖的是操作细节，这些细节放在 README 里会显得杂乱，但代理在触碰任何东西之前确实需要知道。

它没有模式，没有 YAML，没有需要学习的特殊语法。它只是带有标题的Markdown。代理会阅读文本，并将其视为该仓库的长期指令。

为什么 AI 编码工具开始使用 AGENTS.md

每个编码代理都有同样的盲点：会话之间没有记忆。关闭终端，你教会它的所有东西都会消失。打开一个新会话，你又得回到解释：是的，我们用的是make test-integration而不是pytest，还有，这个遗留文件夹确实还在故意使用回调。

如果没有持久的指令文件，代理往往会：

• 运行错误的设置或测试命令，破坏你的工作流
• 默认采用训练数据中最常见的编码风格，而不是你的
• 忽略项目约定，