CLAUDE.md 还是 AGENTS.md？Claude Code 已能直接读 AGENTS.md，官方还说新项目可以先不写

如果你的仓库里同时放着 CLAUDE.md 和 AGENTS.md，两份内容大同小异，还要靠脚本保持同步，这件事现在可以停了。Anthropic 官方文档写明，Claude Code 从 2.1.277 版起，在工作目录及上层没有 CLAUDE.md 时，会直接读取 AGENTS.md；Claude Code 团队的 Thariq Shihipar 在 9 月 29 日的 Latent Space 播客里还更进一步：他认为现在开新项目，也许连 CLAUDE.md 都不必先写。

事实核查截至 2026-10-06。读取规则取自 Claude Code 官方文档，播客内容取自 Latent Space 公开的转录稿，国内一篇 InfoQ 编译稿的标题（“以后都不用”）比转录原话说得更绝，下文会校正。

要点

• 官方文档规定：只有 AGENTS.md、没有任何 CLAUDE.md 时读 AGENTS.md；两者并存时只读 CLAUDE.md，除非你在里面写 @AGENTS.md 导入。
• Thariq 的原话是“我觉得现在新项目可能最好不要 CLAUDE.md”，规则按“反复出现的失败模式”再加；他没有说静态指令文件已经没用。
• Gloaguen 等人的论文（arXiv:2602.11988）测得：上下文文件整体不提高任务成功率，推理成本平均增加 20% 以上，仓库概览尤其没用。

这场争论是怎么来的

AGENTS.md 之争的起点，是 Shopify CEO Tobi Lütke 在 2026 年 8 月 25 日发的一条推文。他说在考虑禁用 Claude Code，直到它愿意读 AGENTS.md 和 .agents/skills。据 The New Stack 报道，他的理由是 Shopify 有数千名开发者在同一个 monorepo 里工作，不同人用不同的 AI 编码工具，这两类文件又按目录树递归生效，总有目录只放了其中一份，“一部分开发者就在被‘切掉脑叶’的状态下干活”。他把团队为此写的同步自动化称作“stupid complexity tax”。

AGENTS.md 是一份写给编码 agent 看的“README”，官网称已有超过 6 万个开源项目使用，列出的兼容工具包括 Codex、Cursor、Gemini CLI、Windsurf、GitHub Copilot 编码 agent 等。Claude Code 此前只读自家的 CLAUDE.md。The New Stack 提到，一条关于递归发现 AGENTS.md 的需求曾被 Anthropic 以“不做”关闭。

一个多月后，局面变了。

现在到底读哪个文件

Claude Code 官方文档的 AGENTS.md 一节给出了完整规则，核心是下面这张决策图。

按文档，几种常见情况的结果如下。

仓库里有什么	Claude Code 默认读什么
只有 AGENTS.md	AGENTS.md，启动时会提示 no CLAUDE.md found; AGENTS.md loaded
AGENTS.md 和 CLAUDE.md 并存	只读 CLAUDE.md
CLAUDE.md 里写了 @AGENTS.md	CLAUDE.md，并通过导入带上 AGENTS.md
只有 AGENTS.md，但你另有未提交的 CLAUDE.local.md	只读 CLAUDE.local.md，AGENTS.md 被跳过

来源：Claude Code 官方文档“How Claude remembers your project”，2026-10-06 核对。

最后一行是容易踩的坑：CLAUDE.local.md 也算 CLAUDE.md。想两份都读，在 /config 里把 Project instructions 设成 claude-md-and-agents-md（默认值是 claude-md-or-agents-md）。还有两个边界：版本低于 v2.1.281 时，部分会话（文档举的例子是 Amazon Bedrock 或关闭了遥测的会话）只读 CLAUDE.md，这时仍需要 @AGENTS.md 导入；通过这个设置读到的 AGENTS.md 不触发 InstructionsLoaded 钩子。

所以，如果团队除了 Claude Code 还在用 Codex、Cursor 等工具，最省事的做法是：保留一份 AGENTS.md 作为唯一来源，删掉内容重复的 CLAUDE.md。如果某些会话读不到，就留一个只有一行 @AGENTS.md 的 CLAUDE.md 兜底。

Thariq 到底说了什么

Thariq 在 Latent Space 播客（2026 年 9 月 29 日发布，全长约 1 小时 32 分钟）的 28 分 10 秒前后回答了主持人 swyx 的追问：“AGENTS.md，我们要做。”理由是不同模型差别很大，但维护多份文件“实在是太痛苦了”。

接着是被各家转述的那段话，我按转录稿还原要点：

1. 模型越来越强，完成简单任务的下限在上升，所以“极限情况下 CLAUDE.md 会消失”。
2. “也许现在新项目最好不要 CLAUDE.md”，语气是“我觉得可能”，不是产品政策。
3. 如果反复看到同一种失败模式，再把它加进文件。
4. 麻烦在于这些规则因模型而异：Fable 5 的毛病，Fable 5.1 可能已经没有。一份只增不减的失败清单，很可能让 Claude “过度约束”。

这和国内转载的标题有落差。把“可能最好先不写”概括成“以后都不用”，丢掉了他留下的两个条件：规则要靠重复出现的失败来触发，而且要随模型升级重新检验。Anthropic 自己的官方文档今天仍在教人写 CLAUDE.md，建议单个文件控制在 200 行以内，并把只对部分目录有用的规则拆进 .claude/rules/。两种说法并不矛盾：文件没有消失，被淘汰的是“预先写一大篇”这个习惯。

有数据支持“少写”吗

有，但结论比口号复杂。arXiv:2602.11988《Evaluating AGENTS.md》（Gloaguen 等，2026 年 2 月提交，9 月 29 日更新到第 3 版）在两类任务上测试了多个模型和编码 agent：一类是 SWE-bench 任务配大模型生成的上下文文件，另一类是真实仓库里开发者自己提交了上下文文件的 issue。

发现	论文原文要点
成功率	提供上下文文件“整体上并不提高任务成功率”
成本	推理成本平均增加 20% 以上
适用范围	不同模型、不同 agent、生成文件和人写文件都是如此
agent 是否照做	照做：文件里的指令被很好地遵循
哪类内容没用	仓库概览：流行且被模型厂商推荐，但没有帮助
哪类内容有用	论文结论称，文件适合写“非标准的编码约定”

来源：arXiv:2602.11988 摘要，2026-10-06 核对。

这组数据支持的是更窄的主张：别把 agent 读代码就能看出来的东西（目录结构、技术栈介绍）写进去，每一行都在花 token，也在挤占注意力。它并不支持“指令文件一律无用”。论文自己的结论就留了口子：文件适合交代非标准做法。

新项目的三步做法

综合官方文档、播客和论文，一个比较稳妥的起手式：

1. 先跑起来，什么都不写。 用 Opus 5.5 这类新模型开工，观察它在你的仓库里真实的失败方式，而不是凭想象预防。
2. 只记反复出现的失败。 同一个错出现第二、三次再写成一条具体规则，例如“测试命令是 pnpm test，不要用 npm test”“数据库迁移必须用生成命令，不要手写”。写非标准约定，不写仓库介绍。
3. 换模型就复查。 升级模型后把规则逐条删一遍再跑任务，只补回仍会出错的。Thariq 提到团队刚给 skills 加了评测插件，可以比较一个 skill 加上之后是否真的更好；文件本身也值得用同样的方式对待。

指令文件之外，约束写法同样要克制，思路和 Opus 5.5 官方提示词指南里“先降档、删掉替模型思考的旧指令”一致。想看一个把 Claude Code 配成完整工程团队的重度配置样本，可以对照 gstack，再判断你的项目需要多少。

常见问题

还要维护两份文件吗？

大多数情况下不需要。把内容放在 AGENTS.md，Claude Code 在没有 CLAUDE.md 时会直接读它。仅当你的环境读不到（旧版本，或文档列出的部分会话类型）时，才加一个内容为 @AGENTS.md 的 CLAUDE.md。

“先读 AGENTS.md”有用吗？

不稳。官方文档说这样写只有当 Claude 自己决定去打开那个文件时才生效，建议改成 @AGENTS.md 导入，或者删掉 CLAUDE.md 让它直接读。

指令文件是硬性规则吗？

不是。官方文档强调它们是上下文，不是强制配置。需要“无论如何都不许做”的约束时，应该用 PreToolUse 钩子，而不是在文件里多写几句。

我们的判断

对多工具团队，Claude Code 开始直接读 AGENTS.md 是实打实的省事。Thariq 那番话更值得记的是方法而不是预言：指令文件是对模型缺陷的补丁，补丁要随模型更新而重验。今天写下的每一条规则，下个模型版本之后都该被当成待审查的假设，而不是资产。

本文参考了 InfoQ 编译的播客整理稿《CLAUDE.md 还是 AGENTS.md？Anthropic 的答案是：以后都不用》（2026-10-06，微信公众号）。