Claude Code 2.1.277 开始兼容 AGENTS.md：加载优先级与 mods 机制解析
文章目录
- [Claude Code 2.1.277 开始兼容 AGENTS.md：加载优先级与 mods 机制解析](#Claude Code 2.1.277 开始兼容 AGENTS.md：加载优先级与 mods 机制解析)
本文面向使用 Claude Code 与 AGENTS.md 的开发者，梳理 2.1.277 版本的兼容改动、项目说明文件的加载优先级，以及支撑这次改动的新扩展机制 mods。
我们公司是做软件开发的，现在用AI编程越来越多，每个人用的AI编程工具也不一样。我自己用的是Claude Code，同事有人用Qoder，还有人用Cursor和DeepSeek Harness。同一个项目，给AI看的"说明书"要备两份。
这两天刷到Claude Code工程师Thariq发帖，说从2.1.277版本开始，文件夹里没CLAUDE.md的话，Claude会自己去找AGENTS.md来读。评论区连OpenAI Codex负责人Tibo都跑来握手了。
我去官网查了一下，大概了解了。下面给大家分享一下这次改了什么，感兴趣的可以接着往下看。
一、这次改了什么
从Claude Code 2.1.277版本开始，项目文件夹里要是没有CLAUDE.md，它会自己去找AGENTS.md来读。
这个版本是9月18日发布的。9月19日，Claude Code团队工程师Thariq在X上发了官宣帖，帖子一小时就冲上百万浏览。
我截了一下原帖。
图：Claude Code官宣帖
原帖也说了，这个行为不是强制的，你可以在 /config 里自己切换，其实就是给项目里那份"给AI看的说明书"多开了一个入口。
二、两份说明书的由来
AGENTS.md本质上就是一份写给AI看的README。
它最早来自OpenAI的Codex团队，2025年8月推出来，同年12月捐给了Linux基金会下面的智能体AI基金会。
到2025年底，全球已经有六万多个开源项目在用它，Codex、Cursor、GitHub Copilot、Gemini CLI、Devin这些工具都读。
Anthropic自己就是那个基金会的白金会员，还把自家的MCP协议捐了进去。可自家主力编程工具，偏偏一直只认 CLAUDE.md。
这导致了一个问题：同一个项目分给两个外包各写一份交接文档，内容差不多，改了一份忘了另一份，最后AI拿着过期文档干活，写出来的代码风格跟团队规范南辕北辙。
GitHub上那条"请支持AGENTS.md"的功能请求，从2025年8月一直挂到2026年9月，攒了5168个赞，是整个Claude Code仓库里票数领先的功能请求，高出第二名四倍。
消息一出，OpenAI Codex负责人Tibo第一时间跑来留言。
图：Tibo的回复
评论区也被"终于统一了"给刷屏了。
三、加载规则和坑
这次不是把 CLAUDE.md 删除了，它还在，优先级也还在。只有项目里确实找不到它，Claude Code才会去读 AGENTS.md。
读子目录里的文件时也一样。如果那个子目录有自己的 AGENTS.md，会按目录层级补上。
/config 里的项目说明那一栏，可以切成三档：只用CLAUDE.md、没有CLAUDE.md时回退到AGENTS.md（默认）、两类文件同时加载。
整个流程我整理成了一张图。
图：Claude Code加载逻辑图
项目里的 CLAUDE.local.md 也算数。
CLAUDE.local.md 是开发者放私人笔记的地方，比如一个测试账号、一个沙箱地址。可它同样会被算进检查里。
也就是说，团队里只要有一个人本地建了 CLAUDE.local.md，他那边就不会再加载 AGENTS.md 了，而且什么提示都没有。
这个逻辑其实跟家里贴便签一样。冰箱上贴着全家公约，你自己又贴了张私人备忘，结果大家只看你那张，公约直接被无视。
稳妥的解法，是在 CLAUDE.md 里写一行 @AGENTS.md 显式导入，这样子兼容性更稳。
我这边就是这么配的。
图：CLAUDE.md里的导入配置
另外，这个功能目前还不支持Amazon Bedrock、Google Vertex和Microsoft Foundry，走这三条路线的暂时用不上。
四、mods机制
AGENTS.md支持没有硬写进Claude Code核心代码，它是用Claude Code mods做出来的，也是第一个内置mod ，源码已经公开在官方仓库的 mods/agents-md 目录里。
Thariq在第二条帖子里说，mods是他们接下来要推出的、用来定制Claude Code运行框架的方式。
mods你可以理解成给Claude Code开的改装口。
以前这些全是官方定好的，扫上下文、加载提示词、组织会话，开发者都插不上手。现在关键节点留出了扩展位，读什么说明书、怎么读，后面都可以自己写。
目前编程智能体的运行框架，正在分成两条路。
Claude Code mods这条，是在打磨好的成品上开天窗，零配置即开即用，扩展受控。
DeepSeek Harness那条，是从零搭积木，一切皆插件，连界面都是插件。自由度很高，但学习曲线也陡。
五、缺点提醒一下
第一，格式通了并不是生态统一。.agents/skills 和 .claude/skills 还是两套目录，各家模型对system prompt的组织偏好也没变。
第二，两份文件并存时，重复内容和优先级冲突反而成了新的维护负担。同一条约定写两处，改一处忘一处，AI读到的是自相矛盾的指令。
第三，社区并没有一边倒叫好。X上很热闹，r/ClaudeAI那边就不太买账，有人直接说这就是个迟到了很久的小改动，算不上什么新能力。
第四，AGENTS.md表达不了工具专属的能力。比如Claude Code的子智能体编排，这些还是得留在 CLAUDE.md 里。
有疑问的话可以在评论区留言交流。觉得有用的话，欢迎点赞关注。
参考资料
Claude Code官方变更日志 https://code.claude.com/docs/en/changelog
mods/agents-md源码目录 https://github.com/anthropics/claude-code/tree/main/mods/agents-md
AGENTS.md官方站点 https://agents.md/
版权声明：本文为原创文章，采用 CC 4.0 BY-SA 版权协议，转载请注明出处。