AGENTS.md 正在成为新的 README.md，我这个博客仓库就靠一份这种文件喂着 AI 干活

哈喽，我是飞飞。

事情是这样的。前阵子我翻 agents.md 那个官网，看到一行字：现在有 6 万多个开源仓库里躺着一个叫 AGENTS.md 的文件。我愣了一下，因为去年 8 月这个数字还是 2 万。半年翻了三倍。我自己这个博客仓库里也躺着一份同类的文件，每天我让 AI 改代码、写文章，全靠它兜着。所以今天想跟你聊聊这个正在悄悄变成「标配」的东西，它到底是干嘛的，为什么你下一个项目可能也该备一份。

AGENTS.md 到底是个什么文件

先说人话。AGENTS.md 就是一个写给 AI 编程助手看的项目说明书。

这里得先翻译两个词。所谓 agent，就是一个能自己动手干活的 AI，它不光跟你聊天，还能真去读你的文件、改你的代码、敲命令跑测试。你现在用的 Cursor、Codex、Claude Code，背后都是这种 agent。而 AGENTS.md，官方自己的定义就一句话：把它当成「给 agent 看的 README」。

你想想 README.md 是干嘛的。它是写给人看的：这项目是干啥的、怎么装、怎么跑、怎么贡献代码。一个新人 clone 下来，先看 README 上手。AGENTS.md 的位置一模一样，只是读者换成了 AI。每次你开一个新对话，AI 对你这个项目其实是「失忆」的，它知道怎么写 Python，但不知道你们团队用 pnpm 不用 npm、不知道 vendor 那个目录碰都不能碰、不知道提交前必须先跑 lint。这些它从代码里推不出来的规矩，就该写进 AGENTS.md。

最让我觉得舒服的一点：它就是一个普普通通的 Markdown 文件。没有新语法，没有新格式，不用学任何东西。你会写 README 就会写它，放在仓库根目录就行。

为什么 AI 干活非得有这么一份规则

这事我有特别真切的体感，因为我天天踩这个坑。

我这个博客仓库根目录就有一份这种文件，叫 CLAUDE.md（Claude Code 的版本，下面会讲它俩的关系）。它一开始很短，就几行说明这是个 Hexo 博客。后来越喂越厚。为什么厚？因为每次 AI 翻车一回，我就往里加一条。

举个最具体的。我那套写文章的流水线特别忌讳「AI 腔」，比如中文破折号那个长长的「——」，模型一写就停不下来，一篇能塞二十几个，读者一眼就闻出机器味。我光靠每次对话里提醒它没用，下回开新对话它又忘了。后来我把这条直接钉进 CLAUDE.md：正文禁用「——」，写完必须自己 grep 一遍清干净，还规定了一篇要 2000 到 2500 个中文字。再比如发公众号那段，我被坑过一次，就写死了一行规矩：发布接口返回 result.success 是 false 就当失败处理，别重试也别抛异常。这些条目没一条是凭空想出来的，全是某次翻车之后补进去的疤。

这就是 AGENTS.md 存在的全部理由。AI 的本事够大，缺的是「纪律」和「上下文」。它不知道你这个项目的脾气，你不写下来，它每次都得重新猜，每次都可能猜错。把规矩落到一个文件里，它每次开工先读一遍，相当于你提前把这些坑给它指出来了。我现在最不敢删的就是这个文件，删一条等于把一个踩过的坑重新埋回去。

它怎么就成了「标准」

这事的有意思之处在于，AGENTS.md 不是某一家关起门来定的。

它最早是 OpenAI 在 2025 年 8 月随 Codex 一起推的。但很快就不只是 OpenAI 的东西了。Cursor、Google 的 Jules、Amp、Factory 这些团队一起协作把它做成了一个开放格式。到 2025 年底，OpenAI 干脆把它捐给了 Linux 基金会下面的 Agentic AI Foundation，跟 Anthropic 把 MCP 捐出去、Block 把 Goose 捐出去是同一批操作。等于说它现在是个有中立组织托管的公共标准，不绑在任何一家身上。

支持它的工具现在排起来挺吓人。Codex、GitHub Copilot、Cursor、Windsurf、Amp、Devin、Aider、Zed、Jules、VS Code、JetBrains 的 Junie，二十八个往上数，都原生读 AGENTS.md。GitHub Copilot 是去年 8 月加的原生支持。这个意思是，你写一份 AGENTS.md，团队里有人用 Cursor、有人用 Codex、有人用 Copilot，大家共享同一份规矩，不用每个工具单独维护一套。这正是它能半年从 2 万涨到 6 万仓库的原因：它解的是「多个 AI 工具各认各的配置文件」这个真痛点。

普林斯顿那边还做过一个测试，拿 Codex 在 10 个仓库 124 个真实合并过的 PR 上跑，每个任务跑两遍，一遍有 AGENTS.md 一遍没有。结论方向是：有这份文件，而且文件写得短的时候，agent 表现更好，因为它少花时间读说明、多花时间真干活。这条挺反直觉，我后面说怎么写的时候会再提。

那它跟 CLAUDE.md、Cursor Rules 是什么关系

这块得讲清楚，因为很多三方文章写错了，我差点也被带沟里。

我天天用的是 Claude Code，它读的文件叫 CLAUDE.md，不是 AGENTS.md。Cursor 早年有自己的 .cursorrules，后来挪到了 .cursor/rules 目录。GitHub Copilot 读的是 .github 里的 copilot-instructions.md。也就是说在 AGENTS.md 出来之前，每家有每家的文件名，你想让所有工具都听话，得维护好几份内容八成重复的文件。这就是当初那一地鸡毛。

关键的坑在这：网上不少指南说「Claude Code 没有 CLAUDE.md 时会自动回退去读 AGENTS.md」。我专门查了 Anthropic 的官方文档，没这回事，实测也对不上。Claude Code 就认 CLAUDE.md，Codex 就认 AGENTS.md，俩谁也不会自动去读对方。GitHub 上那个要求 Claude Code 支持 AGENTS.md 的功能请求（编号 6235），攒了五千多个赞，到五月底还开着，没排期。提需求的人理由很实在：CLAUDE.md 这名字太「Claude 专属」了，跟不用 Claude Code 的同事协作时就尴尬。

那两边都用的人怎么办？官方今年五月给的法子是桥接：在 CLAUDE.md 里用 @AGENTS.md 这种写法把后者导进来，或者干脆做个软链接让两个文件名指向同一份内容。一份真东西，两个名字。说白了 Cursor Rules、CLAUDE.md、AGENTS.md 本质是同一件事的不同方言，AGENTS.md 想做的就是那个让大家都能听懂的普通话。我自己暂时还守着 CLAUDE.md，毕竟我这台主力就是 Claude Code，但要是哪天我让 Codex 也来碰这个仓库，我大概率就软链一份 AGENTS.md 过去。

那这份文件到底该怎么写

讲点能直接上手的。我把这份文件该有的东西，配上我自己踩出来的写法，给你捋一遍。

先把环境怎么跑起来写清楚。装什么、用哪个包管理器、怎么启动、怎么跑测试，这是 agent 最容易瞎猜的地方。我仓库里就写死了 hexo clean、hexo g、hexo s 这几个命令，省得它自己乱试。

再往下，写那些代码里看不出来的规矩，这是整份文件最值钱的部分。我那条「禁用破折号、一篇 2000 到 2500 中文字」就是典型，AI 读再多代码也猜不到我对文风这么挑。你那些「这个目录别动」「这个函数从不抛异常」的潜规则，都该落在这。

剩下一块是提交前的纪律。要不要先跑 lint、PR 标题什么格式、要不要顺手补测试。官方给的示例里就有一句特别朴实：「你改了哪段代码，就给它补上测试，哪怕没人要求」。

还有一条我得特意提，就是别写长。普林斯顿那个测试发现短文件反而更好使，我自己也有体感，文件一长 AI 读起来费劲，重点反而被淹了。所以原则是只写「代码里推不出来、又非说不可」的东西，能从代码本身看出来的别啰嗦。大项目还可以在子目录里再放一份，管那一块的特殊规矩，AI 会就近读最近的那份。下面是一份能直接抄走改的最小骨架：

# AGENTS.md

## 项目是什么
一句话说清这项目干嘛、有什么不能踩的硬约束。

## 怎么跑起来
- 安装：pnpm install
- 启动：pnpm dev
- 测试：pnpm test

## 代码规矩
- vendor/ 目录不要改。
- API 客户端从不抛异常，错误走返回值。

## 提交前
- 先跑 pnpm lint。
- 改了代码就补测试，哪怕没人要求。

你别指望一次写全。我这份就是空仓库起步，翻一次车补一条，半年喂成了现在这样。它越用越准，是因为每一条都是真疼过才记下的。

绕了一圈我才回过味来，当年我们给项目写 README 是为了让下一个人能接手，现在写 AGENTS.md，是为了让那个每天替我们干活、却每次开工都失忆的 AI 能接手。读者从人变成了机器，但那份「把项目的脾气交代清楚」的心意，一点没变。

你那个天天用的项目，要是现在让一个 AI agent 直接上手改代码，你觉得它最容易在哪个地方猜错、闯出哪种祸？这个答案，其实就是你那份 AGENTS.md 该写的第一条。