1. 从两份说明书说起这个更新到底解决了什么痛点如果你同时用过 Claude Code 和 Codex大概率经历过这种别扭事项目根目录下躺着一个CLAUDE.md又躺着一个AGENTS.md内容八成是重复的——项目结构、构建命令、代码规范、测试怎么跑两边各写一遍。改了一处忘了同步另一处过两天新来的同事问“到底以哪个为准”你自己都得愣一下。这次 Claude Code 正式支持AGENTS.md本质上就是把这块重复劳动砍掉了。它不再只认自己那套CLAUDE.md而是能直接读取社区里越来越通用的AGENTS.md作为项目级指令来源。换句话说你维护一份面向所有 Agent 的项目说明书就够了Claude Code、Codex 以及其他遵循这个约定的工具都能读同一份文件。先把几个概念理清楚不然后面容易绕晕CLAUDE.mdClaude Code 早期专属的项目记忆文件放在项目根目录用来告诉它这个项目怎么构建、怎么测试、有哪些约定。AGENTS.md一个更中立的约定目标是让不同厂商、不同形态的编码 Agent 都能读同一份项目说明。你可以把它理解成“项目说明书”的通用格式。Agent这里特指能自主读写代码、执行命令、完成多步任务的编码助手不是那种只做单轮问答的聊天机器人。Codex另一款主流的编码 Agent 工具也是AGENTS.md这个约定的重要推动者之一。这个更新适合谁三类人最该关注。第一类是同时用多个 Agent 工具的开发者之前被两份说明书折磨过第二类是团队里负责统一工程规范的想让所有成员的 AI 助手行为一致第三类是刚开始接触 Agent 编码、还没建立项目记忆习惯的新手正好一步到位用通用格式省得以后迁移。提示AGENTS.md不是 Claude Code 独有的东西它的价值恰恰在于“通用”。如果你现在还在纠结要不要迁移先想清楚你是不是真的会用多个 Agent 工具如果只用 Claude Code 一个CLAUDE.md继续用也没问题。我自己的判断是这个改动看着小实际影响挺大。它标志着编码 Agent 的“项目记忆”开始从各家私有格式走向事实标准。以前每个工具都想让你把配置写在它自己的文件里现在大家慢慢意识到重复维护的成本最终是用户买单。谁先支持通用格式谁就少让用户受一份罪。2. 核心机制拆解Claude Code 到底怎么读这些文件2.1 文件优先级与加载顺序要理解这次更新得先搞清楚 Claude Code 读取项目指令的优先级。根据我实际测试和社区反馈它大致遵循这样一个顺序项目根目录的CLAUDE.md如果存在优先级最高项目根目录的AGENTS.md新增支持子目录中的同名文件用于局部覆盖用户级全局配置这个顺序背后的逻辑很直白越靠近项目的配置越具体越应该覆盖全局。而CLAUDE.md排在AGENTS.md前面是为了兼容老项目——如果你两个文件都有Claude Code 会优先信CLAUDE.md避免突然改变行为。但这里有个坑如果你两个文件都留着内容还不一致Claude Code 会以CLAUDE.md为准AGENTS.md里那些更新就被忽略了。所以迁移的正确姿势是二选一别两个都留。2.2 为什么是 AGENTS.md 而不是继续推 CLAUDE.md这个问题值得展开说。Claude Code 完全可以继续只支持自己的CLAUDE.md为什么还要去兼容一个别家推动的格式核心原因是生态位。编码 Agent 这个赛道现在玩家很多如果每家都搞一套私有配置文件用户就被绑架了——你换工具就得重写一遍项目说明。AGENTS.md的出现就是为了打破这个局面它不绑定任何一家谁都可以读。Claude Code 支持它短期看是“让步”长期看是“占位”。当用户发现“我写一份AGENTS.mdClaude Code 和 Codex 都能用”迁移成本就降低了反而更愿意尝试不同工具。这对整个生态是好事对 Claude Code 自己也不是坏事——它少了一个用户不选它的理由。2.3 文件里到底该写什么很多人第一次写这类文件容易写成“项目介绍”。其实 Agent 需要的不是介绍是可执行的指令。我总结了一个实用的内容清单内容类型该写什么不该写什么构建命令npm run build、cargo build“本项目使用现代构建工具”测试命令pytest -x、go test ./...“测试很重要”代码规范缩进用 2 空格、禁止 any 类型“代码要写得优雅”目录约定组件放src/components“目录结构清晰”禁忌事项不要改generated/下的文件“注意不要犯错”看出规律了吗左边是 Agent 能直接执行或判断的右边是给人看的废话。Agent 不需要你告诉它“代码要优雅”它需要你告诉它“这个项目用 ESLint提交前跑npm run lint”。2.4 加载时机与上下文成本还有个细节值得注意这些文件不是每次对话都全量塞进上下文。Claude Code 会在会话开始时读取并根据当前任务相关性决定注入多少。文件写得太长反而会稀释真正重要的指令。我的经验是AGENTS.md控制在 100 到 300 行比较合适。超过这个量就该考虑拆分——把通用规范放根目录把模块特有的约定放子目录的AGENTS.md里让 Agent 按需读取。注意不要把所有东西都堆进一个文件。我见过有人写了 800 行的AGENTS.md结果 Agent 经常忽略中间部分的指令。上下文是有预算的写太多等于没写。3. 实操从 CLAUDE.md 迁移到 AGENTS.md 的完整流程3.1 迁移前的准备工作别急着删文件。迁移前先做三件事第一把现有CLAUDE.md完整读一遍标记出哪些是 Claude Code 专属的比如某些只在 Claude Code 里生效的语法哪些是通用的项目说明。大部分内容其实是通用的专属的很少。第二确认你的项目里有没有子目录级别的CLAUDE.md。如果有这些也要一并考虑。子目录文件通常写的是模块特有约定迁移时保持相对路径不变即可。第三检查有没有其他工具已经在读AGENTS.md。如果 Codex 已经在用那你要做的是合并而不是新建。3.2 具体迁移步骤假设你有一个典型的CLAUDE.md内容大概是这样# 项目说明 ## 构建 npm install npm run build ## 测试 npm test ## 规范 - 使用 TypeScript - 组件放 src/components - 不要修改 generated 目录迁移到AGENTS.md的步骤在项目根目录新建AGENTS.md把CLAUDE.md里的通用内容复制过去删掉 Claude Code 专属的语法如果有补充一些对多 Agent 都友好的说明比如“本文件面向所有编码 Agent”确认无误后删除CLAUDE.md或者保留但清空内容并加一行指向AGENTS.md第五步很关键。如果你直接删CLAUDE.md而团队里有人还在用旧版本 Claude Code可能会突然失去项目记忆。稳妥做法是保留一个占位文件# 已迁移 本项目说明已迁移至 AGENTS.md请以该文件为准。这样旧版本读到CLAUDE.md会知道去看AGENTS.md新版本则直接读AGENTS.md两边都不耽误。3.3 验证迁移是否生效迁移完别假设它一定生效了要验证。我的验证方法很简单在项目里问 Claude Code 一个只有读了AGENTS.md才能答对的问题。比如你在文件里写了“测试命令是npm run test:unit”那就问它“这个项目的单元测试怎么跑”。如果它答对了说明文件被读到了如果它答的是通用的npm test说明没读到或者被忽略了。再进一步你可以故意在AGENTS.md里写一条反直觉的约定比如“所有日志必须用logger.info禁止console.log”然后让它写一段带日志的代码看它是否遵守。遵守了说明指令生效。3.4 多 Agent 共存时的目录组织如果你同时用 Claude Code 和 Codex目录可以这样组织project/ ├── AGENTS.md # 通用项目说明所有 Agent 都读 ├── CLAUDE.md # 可选Claude Code 专属补充如果有 ├── src/ │ ├── AGENTS.md # 模块级说明 │ └── components/ └── tests/ └── AGENTS.md # 测试相关约定原则是能放AGENTS.md的就放AGENTS.md只有确实只对 Claude Code 生效的内容才放CLAUDE.md。这样你的项目对任何 Agent 都是友好的换工具不用重写。4. 踩坑记录迁移过程中最容易出问题的几个地方4.1 两个文件内容冲突这是最常见的坑。你新建了AGENTS.md但忘了删CLAUDE.md两边内容还不一样。结果 Claude Code 优先读CLAUDE.md你改的AGENTS.md完全没生效你还以为是更新没起作用。排查方法临时把CLAUDE.md改名看行为有没有变化。如果变了说明就是优先级问题。4.2 子目录文件路径写错子目录的AGENTS.md里如果引用了相对路径迁移时要特别注意。比如原来CLAUDE.md里写“参考../docs/style.md”迁移后路径基准没变一般没问题。但如果你把文件挪了位置路径就错了。我的习惯是子目录文件里尽量用相对于项目根目录的路径或者干脆用绝对描述“项目根目录下的 docs/style.md”减少歧义。4.3 Agent 忽略文件内容有时候文件写对了Agent 还是不遵守。原因通常有三个文件太长关键指令被淹没指令太模糊Agent 无法判断是否该执行指令和当前任务不相关Agent 主动忽略了解决办法把最重要的指令放在文件最前面用加粗或列表突出指令要具体到可执行比如“提交前必须跑npm run lint”而不是“注意代码质量”不相关的内容拆到子目录文件里。4.4 版本兼容问题不是所有版本的 Claude Code 都支持AGENTS.md。如果你团队里有人用旧版本迁移后他们可能读不到新文件。这时候保留CLAUDE.md占位文件就很重要。另外如果你用的是某些第三方封装的 Claude Code 客户端支持情况可能又不一样。迁移前最好确认一下团队用的版本。4.5 常见问题速查表现象可能原因解决办法改了 AGENTS.md 没反应CLAUDE.md 优先级更高删除或清空 CLAUDE.mdAgent 答非所问文件太长指令被稀释精简到 300 行以内子目录约定不生效路径写错或文件没被读取检查相对路径确认文件位置旧版本读不到版本不支持 AGENTS.md保留 CLAUDE.md 占位多个 Agent 行为不一致各自读了不同文件统一用 AGENTS.md提示迁移不是一劳永逸的事。项目在变Agent 能力也在变AGENTS.md应该跟着项目一起演进。我一般每个月回顾一次把过时的指令删掉把新踩的坑补进去。5. 更进一步把 AGENTS.md 用出体系化价值5.1 从单文件到分层体系单个AGENTS.md能解决基本问题但项目一大就不够用了。我的做法是分层根目录AGENTS.md放全局约定构建、测试、代码风格、禁忌模块级AGENTS.md放该模块特有的约定比如“这个模块用 RxJS注意取消订阅”任务级临时说明在对话里直接告诉 Agent不写进文件这样 Agent 读根目录知道大方向进到具体模块再读模块级文件上下文不会被无关信息占满。5.2 把踩过的坑写进去AGENTS.md最有价值的部分往往不是那些“正确做法”而是“别这么做”。比如“不要用any本项目开了严格模式”“不要直接改dist/那是构建产物”“不要在这个模块用useEffect做数据获取用 SWR”这些禁忌是团队踩坑换来的写进去能帮 Agent 少犯同样的错。我甚至建议专门开一个“已知陷阱”小节把历史上出过问题的操作列出来。5.3 和 CI 联动进阶玩法是把AGENTS.md里的约定和 CI 检查对齐。比如文件里写“提交前跑npm run lint”CI 里就真的跑 lint不通过就拦下来。这样 Agent 写的代码和人工写的代码走同一套标准不会出现“Agent 写的能过人写的过不了”这种荒唐事。5.4 团队协作中的维护约定如果团队多人维护AGENTS.md得有个约定谁改了项目规范谁负责更新文件。最好把这件事写进 PR 模板提醒提交者检查AGENTS.md是否需要同步。我见过最有效的做法是在 CI 里加一个检查如果package.json的 scripts 变了但AGENTS.md没变就发个提醒。虽然不能强制但至少能让人注意到。5.5 面向未来的扩展思路AGENTS.md这个约定还在演进。可以预见的方向包括更结构化的格式比如用 YAML front matter 声明元信息、更细粒度的作用域控制、和工具链更深的集成。现在能做的是保持文件内容的中立性——别写太多绑定某个工具的东西。这样无论未来哪个 Agent 工具崛起你的项目说明都能继续用。我个人在实际操作中的体会是AGENTS.md最大的价值不是省了那点重复劳动而是逼着团队把“项目该怎么干活”这件事写清楚。很多团队其实没有明确的工程规范全靠口口相传。有了这个文件新人和 Agent 都能快速对齐这才是真正的收益。最后分享一个小技巧如果你不确定某条指令该不该写进去就问自己——“如果新来的同事不知道这条会不会犯错”会就写不会就别写。文件越精炼Agent 越容易抓住重点。