昨天开发者圈子里最热的一条更新，不是什么新模型发布，而是 Claude Code v2.1.277 更新日志的第一行：项目路径里没有 CLAUDE.md 时，会自动找 AGENTS.md 来读。Anthropic 工程师 Thariq Shihipar 的宣布帖在 X 上被记录到超过 2.4 万赞、292 万浏览。 挂了一年多的 GitHub issue #6235 以 completed 状态关闭，留下 401 条评论、6657 个 reaction。中文圈的 AI 早报一夜跟进，传播最广的一句话却是「不用再维护 CLAUDE.md 文件了」。知乎微博
如果你的项目里躺着一份写了很久的 CLAUDE.md，很不幸：这句话大概率说错了。升级之后你该干嘛还是干嘛，老项目很可能是全场最「无感」的那个。这篇把这次支持的默认行为、一个藏在队友机器上的坑、插件通道留下的行为差异，以及那篇「上下文文件不一定提效」的论文一起摆清楚。看完你会知道：这次到底值不值得动你的仓库，以及动之前先查哪一行。
一、改的不是「兼容」，是「二选一的兜底」
先把官方文档级别的细节摊开，这次支持有四个容易漏掉的前提：
默认值是回退，不是并读。 配置项默认 `claude-md-or-agents-md`：只要项目路径里存在 CLAUDE.md，AGENTS.md 就完全不会被读取；找不到 CLAUDE.md，agents-md 才接手。想让两份文件同时生效，要手动改成 `claude-md-and-agents-md`。知乎
CLAUDE.local.md 也算「有自己的文件」。 团队可能已经把仓库里的 CLAUDE.md 删了、准备统一维护 AGENTS.md——但只要某位成员机器上还留着一份 CLAUDE.local.md，他本机的回退就不会触发，AGENTS.md 读不到，而且整个过程不报任何错。 这是本次更新最隐蔽的坑。知乎
适用范围有限制。 v2.1.277 更新日志写明 Bedrock、Vertex、Foundry 尚未覆盖；关闭 telemetry 或拿不到 feature flags 的会话不支持；安装或升级后的第一个会话也不可用，要从下一次会话开始。
实现方式是 mod，不是核心。 这项功能由名为 agents-md 的内置 mod（plugin.json 版本 0.1.0）通过 hooks 机制接入既有指令加载流程。 好处是沿用现成扩展机制、可关闭可替换；代价是插件通道和核心加载器之间必然存在行为差异。
所以准确的说法是：从来没写过 CLAUDE.md 的新项目，立刻受益；两份文件并存或只有一份 CLAUDE.md 的老项目，默认什么都不会变。 Hacker News 上 572 分、201 条评论的讨论，重心也全在默认值和适用范围——工程师关心的从来不是「哪家公司低头了」，而是「我的机器上到底读不读」。
二、为什么等了393天，又为什么突然改了
时间线值得复盘，因为它解释了一个工具会不会继续变：
2025-08-21，issue #6235 提出，要求 Claude Code 支持 AGENTS.md，它随后成了整个 Claude Code 仓库里票数最高的功能请求。36氪
期间社区自己曲线救国：软链接、脚本同步、让 CLAUDE.md 和 AGENTS.md 都指向第三份「说明书」，各种方案在开发者微博和知乎上流传了一年；
2025 年 12 月，AGENTS.md 标准被捐赠给 Linux 基金会旗下的 Agentic AI Foundation（AAIF）。 所谓「OpenAI 的标准」是新闻标题的简化，捐赠之后它的治理已不属于任何一家公司；知乎
2026-08-17，issue 以 completed 关闭（从创建到关闭 361 天）；
2026-08-25，Shopify CEO Tobi Lütke 公开表示：正在考虑在 Shopify 禁用 Claude Code，直到它愿意读 AGENTS.md 和 .agents/skills。 他给了这个词：多工具团队维护两套指令文件，交的是「复杂度税」；
Thariq 当天回应：Anthropic 不认为模型家族可以互换，system prompt 会显著影响性能——但他同时承认，这套文件维护起来很费事，「对所有人都不值得」。无论技术理由是否成立，成本实实在在落在用户头上；
2026-09-18/19，宣布帖发出，v2.1.277 上线，从 issue 创建到发布帖正好 393 天。
把这条线连起来看，这不是「命名权之争结束了」的爽文，而是：标准归属中立化（Linux 基金会）+ 头部企业客户的真实成本 + 一年 401 条评论的社区压力，三者叠到了 Anthropic 原来那条「模型不同、提示词要分开调」的技术理由撑不住的位置。
三、就算读到了，两条通道也不等价：那 8 项差异
agents-md 的 README 列出了 8 项与核心加载器的差异，每一项都对应插件通道今天拿不到的加载器事实。其中有几项会直接改变行为：
嵌套目录里指令文件的触发时机不同；
上下文压缩后的规则恢复行为不同；
`–add-dir` 外部目录、subagent 重复挂载的处理不同；
可见性问题：`/memory` 不显示 AGENTS.md。
对大部分单文件小项目，这些差异无感；但你的项目越依赖嵌套规则、外部目录、软链和 subagent，「改了文件名」就越不等于「迁移完成」。一个真实的团队故障模式是：CLAUDE.md 里的构建命令更新了，AGENTS.md 忘了同步，换个工具跑，错误才暴露。这次更新减少了复制文件的必要，但没有把两条加载路径合并成一条。知乎
四、反直觉的部分：统一标准 ≠ 自动提效
功能落地前后，ETH Zurich 等机构作者的一篇论文（arXiv:2602.11988）问了个更冷的问题：仓库里的上下文文件，到底能不能提高 coding agent 的任务完成率？作者在 SWE-bench 任务和真实仓库开发者提交的上下文文件上做了两类评测，结论不乐观——提供上下文文件整体没有提升任务成功率，平均推理成本却增加了超过 20%（token 口径），且这个结论跨模型、跨 agent、跨文件来源都成立。知乎
拆开看有一个更有用的区分：指令类内容（构建命令、测试要求、非标准约定、不能碰哪些目录）agent 会认真遵守；仓库概览类内容对完成任务没有帮助——而后者恰恰是厂商文档最爱建议写进去的部分。
对钱包的影响也分人：按 token 计费的团队，这 20% 直接进账单；包月套餐用户账单上看不出边际，但上下文窗口实实在在被占掉。所以这次事件真正值得做的动作不是庆祝标准统一，而是给上下文文件瘦身：能删的概览删掉，只留硬规则和坑。
五、按你的状态对号入座
新项目、还没写 CLAUDE.md：直接用 AGENTS.md，三节就够——技术栈与目录结构、代码与提交规范、已知坑和注意事项。别写 README 式概览，那是论文点名没用的部分。
老项目、两份文件并存：不要先删文件。第一步 diff 合并：哪些是仍然有效的共同事实，哪些真是 Claude 专属，冲突的指令回到仓库脚本和 CI 去裁决，而不是按文件名决定谁天然正确；第二步选路线——保留一个极简 CLAUDE.md、用官方支持的导入行指向 AGENTS.md（Claude 侧推荐做法），或改配置为 `claude-md-and-agents-md`；第三步开新会话验证，别在旧聊天窗口里问「你读到规则了吗」就判定迁移成功。
Codex + Claude Code 混用团队：注意 Codex 的规则是「同一目录最多选一份项目指令文件」，AGENTS.override.md 优先于 AGENTS.md，备用文件名是候选顺序、不是额外加载清单。 共用文字不会把加载器也统一，两边要各自确认一遍实际读取路径。知乎
走 Bedrock/Vertex/Foundry 的企业用户：这次没覆盖，先别动，继续维护 CLAUDE.md。
本机有 CLAUDE.local.md 的人：现在就去看看它是不是还在悄悄屏蔽 AGENTS.md。
六、接下来盯什么
agents-md mod 的版本——还是 0.1.0 一天，8 项差异就还在一天；
默认值会不会从「二选一」变成「并读」，那才是「一份说明书走天下」真正成立的时候；
Claude Code 对 `.agents/skills` 的支持——那是 Tobi Lütke 诉求的另一半，还没落地；
上下文文件评测的后续复现——如果「不提效、只烧 token」被反复证实，两份文件的价值逻辑还要再改写一次。
AI 编程的竞争，正在从「谁的模型写代码更准」转向「谁的项目上下文标准说了算」。标准统一解决互操作和维护，效果是否进账，还得看你文件里写的是指令还是废话。今晚升级完之后，最划算的一个动作是：先查你机器上那份 CLAUDE.local.md 在不在。
