Claude Code 开始支持 AGENTS.md：Agent 指令标准之战结束了

9 月 18 日的 Claude Code v2.1.277 更新日志里，藏着一条不起眼但影响深远的更新：开始支持 AGENTS.md——如果项目里没有 CLAUDE.md，Claude Code 会转而读取 AGENTS.md。看起来只是"多认一种文件名"，实际上是一个行业级信号：Agent 指令文件的标准之战，正在走向统一，而赢的很可能是 OpenAI 定下的 AGENTS.md。

这篇讲清楚：AGENTS.md 是什么、为什么 Claude Code 要认它、以及对你手里的项目意味着什么。

从"各家方言"到"普通话"

先捋一下混乱的现状。过去一年，每个 Agent 工具都发明了自己的"项目说明书"：Claude Code 认 CLAUDE.md，Cursor 认 .cursorrules（后来是 Rules），Windsurf 有自己的 memory，Codex 认 AGENTS.md。结果是：同一个项目，用三个工具要写三份指令文件，内容还大同小异——技术栈、代码规范、常用命令、不要碰的目录。

OpenAI 在 2026 年把 AGENTS.md 推成了开放标准：一个放在仓库根目录的 Markdown 文件，用统一格式告诉任何 Agent"这个项目是什么、怎么工作、有什么规矩"。Cursor、Windsurf 陆续跟进，现在 Claude Code 也认了。当最固执的那个（Anthropic 有自己的 CLAUDE.md 传统）都开始兼容对手的标准时，标准之战基本就结束了。

注意 Anthropic 的做法很讲究：不是废掉 CLAUDE.md，而是"没有 CLAUDE.md 时才读 AGENTS.md"，而且可以在 /config 的 "Project instructions" 里改。这是一种体面的投降——自家传统保留，行业标准兼容。两边都不得罪，但方向已经很明显了。

为什么这件事比看上去重要？

第一，它降低了"换工具"的成本。以前从 Cursor 换到 Claude Code，第一件事是重写指令文件；以后一份 AGENTS.md 走天下。工具厂商当然不喜欢——锁定效应少了一块。但对用户是好事，竞争会回到真正重要的地方：模型能力、执行可靠性、价格。

第二，它让"指令"变成了代码资产。当 AGENTS.md 成为标准，它就和 README、CI 配置一样，成了仓库的一等公民：可以 code review，可以版本管理，可以跨项目复用。已经有团队开始维护"组织级 AGENTS.md 模板"——新项目脚手架自带一份，好的实践沉淀下来。这是从"个人技巧"到"工程资产"的跃迁。

第三，它在定义 Agent 的"第一性原理"。AGENTS.md 标准里最有价值的部分，不是格式，而是它逼你回答的三个问题：这个项目是干什么的？（上下文）有哪些铁律不能碰？（约束）常用工作流是什么？（流程）答不上来的团队，说明项目本身就没想清楚——文件是镜子。

实操：一份好的 AGENTS.md 长什么样

别写成长篇大论。Agent 的注意力也是预算，AGENTS.md 的黄金长度是 50-150 行。结构建议：

• 项目一句话：这是什么、给谁用、技术栈关键词。让 Agent 第一次读就建立心智模型。
• 铁律区（不超过 10 条）：比如"所有数据库 migration 必须可回滚""不许直接 push main""测试覆盖率低于 80% 不许合"。铁律要少而硬，多了等于没有。
• 常用命令：怎么跑测试、怎么起本地环境、怎么 build。别让 Agent 去猜，猜就会错，错了就浪费你的 token 和时间。
• 禁区：哪些目录是生成的别碰，哪些文件是手写的别改，哪些操作（删库、发版）必须先问人。
• 代码风格三句话：够了。别把 eslint 配置抄一遍，Agent 看不懂长篇规则，要的是"优先组合 over 继承"这种能直接用的判断。

一个反模式警告：别在 AGENTS.md 里写"需求"。它是"宪法"，不是"任务单"。把"给登录页加个记住我"这种一次性需求写进去，文件很快就烂掉。需求走 issue、走 prompt；AGENTS.md 只写长期有效的东西。判断标准：这条规则三个月后还成立吗？不成立就别写。

各家 AGENTS.md 实现对比：细节里有魔鬼

"都支持 AGENTS.md"不等于"支持得一样"。三家的实现细节，决定了你的文件怎么写：

• Codex（原生）：AGENTS.md 是亲儿子。支持多层级——根目录一份，子目录可以再放一份，子目录的会"覆盖+补充"根目录的。还支持 AGENTS.md 里引用其他文件。写 Codex 的 AGENTS.md，可以大胆用"分层"结构。
• Claude Code（兼容）：只有"没有 CLAUDE.md 时"才读 AGENTS.md，优先级是 CLAUDE.md > AGENTS.md。而且目前是"整文件读取"，不支持子目录多层级。如果你的项目两种文件都有，记得保持一致——否则 Claude Code 和 Codex 读到的"宪法"是不一样的，这是埋雷。
• Cursor（跟进）：通过 Rules 系统兼容 AGENTS.md，但 Cursor 的 Rules 有自己的"作用域"概念（全局/项目/文件级），AGENTS.md 的内容会被"翻译"进这个体系。实际效果接近，但调试时要注意：Cursor 里看到的"生效规则"和文件原文可能不完全一致。

实操结论：一份 AGENTS.md 想三家通用，就按"最小公分母"写——只用根目录一份、只用通用 Markdown（标题、列表、代码块）、不用任何一家的专有语法。想用高级特性（分层、引用），就接受"在 Codex 上效果最好，其他家降级"的现实。

迁移实操：从 CLAUDE.md 到 AGENTS.md 的三步

如果你已经有 CLAUDE.md，别急着删，按这三步迁：

第一步：复制+改名，先跑起来。把 CLAUDE.md 复制成 AGENTS.md（暂时保留 CLAUDE.md），在三个工具里各跑一个标准任务，对比效果。这个阶段的目标是"验证兼容性"，不是"优化"。

第二步：删专有语法，降级到通用。CLAUDE.md 里可能写了 Claude Code 专有的东西（比如 @ 引用、特殊的 frontmatter），AGENTS.md 里要删掉或改写成自然语言。原则：AGENTS.md 里只写"人话"，不写"咒语"——人话三家都懂，咒语只有一家懂。

第三步：删 CLAUDE.md（可选），或保留做"增强层"。两条路线：彻底迁移派——删掉 CLAUDE.md，一份 AGENTS.md 走天下，简单干净；双轨派——保留 CLAUDE.md，里面只放 Claude Code 专属的增强指令（比如 MCP 配置），通用部分放 AGENTS.md。我的建议：个人项目走彻底迁移，团队项目走双轨（因为团队里一定有人只用 Claude Code）。

进阶：组织级 AGENTS.md 模板

当你有 3 个以上项目，值得建一份"组织级模板"：新项目脚手架自带 AGENTS.md，包含你们团队的通用铁律（分支策略、测试要求、代码风格三句话、禁区）。每个项目的 AGENTS.md = 组织模板 + 项目特有部分。

这件事的价值被低估了：它在把"团队的工程文化"变成"可执行的代码"。以前工程文化靠口口相传、靠 code review 时念叨；现在写进 AGENTS.md，每个 Agent 第一次进项目就读到了。新人（人类新人也一样） onboarding 的第一件事，不再是"找老人问规矩"，是"读 AGENTS.md"。一份好的组织级模板，顶半个 Tech Lead 的"立规矩"工作。

维护建议：组织模板放单独仓库，版本化管理，各项目用 git submodule 或脚手架同步。模板的变更走 PR review——改模板就是改"宪法"，必须比改代码更慎重。

FAQ：5 个常见问题快问快答

Q1：已经有 CLAUDE.md，还要 AGENTS.md 吗？A：看你用几个工具。只用 Claude Code——不用，CLAUDE.md 够了。用两个以上——要，一份 AGENTS.md 省掉 N 份维护。

Q2：AGENTS.md 和 README 有什么区别？A：README 是给人看的（"这个项目是干嘛的"），AGENTS.md 是给 Agent 看的（"在这个项目里干活要守什么规矩"）。README 讲"是什么"，AGENTS.md 讲"怎么干"。两个都要有，不互相替代。

Q3：AGENTS.md 里能写密码、密钥吗？A：绝对不能。它要进 git、要给 Agent 读，写密钥等于"把钥匙贴在门上"。密钥走环境变量，AGENTS.md 里只写"密钥从哪个环境变量读"。

Q4：多长的 AGENTS.md 合适？A：50-150 行。少于 50 行，大概率漏了关键约束；多于 150 行，Agent 记不住，等于没写。超了就拆：通用部分放根目录，模块特有的放子目录（Codex 支持分层）。

Q5：AGENTS.md 需要多久更新一次？A：跟着"铁律"走。铁律变了（比如换了分支策略），当天更新；铁律没变，三个月 review 一次。把它加入"项目健康度检查"清单，和依赖升级同一天做。

一句话总结

Claude Code 兼容 AGENTS.md，标志着 Agent 工具链的一个阶段结束了："我的地盘我做主"的方言时代过去，"一份文件走天下"的普通话时代来了。对独立开发者，这是个动手的好时机——花一个小时给你的主力项目写一份 100 行的 AGENTS.md，试试在 Claude Code、Codex、Cursor 里各跑同一个任务，对比效果。你会发现，工具之间的差距，远没有"有好指令"和"没指令"之间的差距大。标准统一之后，拼的就是谁的"宪法"写得好。而写宪法的能力，恰恰是人类最后的护城河之一。