Claude Code 使用 AGENTS.md 不生效的原因排查

Claude Code 在2.1.277版本开始支持 AGENTS.md。

AGENTS.md 是个跨工具的约定，Codex、Cursor 这些工具都在使用。而 Claude Code 之前只认自己的 CLAUDE.md，于是一个团队只要有人使用不同的Agent开发工具，就得维护两份规范文件。如果改了一份忘了另一份，就会出现一些意想不到的我恩替。

这次 Claude Code 的更新就是来解决这件事的：项目里没有CLAUDE.md的时候，Claude Code会转去读AGENTS.md。

但是有不少开发者把AGENTS.MD文件放到项目里后，却发现Claude Code 并没有任何反应，文件根本没有生效。这是怎么回事？

真正的原因，是项目目录里还躺着别的 Markdown 文件。下面就给大家介绍一下原因和深层次的规则。

1. 四种常见原因

项目里已经有CLAUDE.md或CLAUDE.local.md。

当项目中同时存在上面任意一个文件的时候，AGENTS.md 就会被跳过，而且没有任何提示，日志里既不会有警告也不会报错。

这是最常见的一条，尤其是 CLAUDE.local.md 文件：很多人习惯于用它记录自己的本地偏好和备忘。如果创建这个文件以后，团队规范从此对他一个人失效。

你建的是AGENTS.local.md。

照着 CLAUDE.local.md 的用法类推是不成立的，这个文件名不被支持，写了也不读。

这是升级后的第一次会话。

安装或者升级到 2.1.277 之后的第一次会话不生效，Claude Code 会从第二次会话才开始读 AGENTS.md。所以别在当天验收，会误判成没生效。

你想让两份同时生效，但配置写错了位置。

相关配置必须写在全局的 ~/.claude/settings.json 里，写进项目级或本地配置会被直接忽略，见第 3 节的配置片段。

2. 项目里放哪些文件，谁会被读

Claude Code 启动时会从项目里挑一份项目级指令文件，挑中的那份才生效。

从上表可以看出，项目根目录下只要有 CLAUDE.md 或 CLAUDE.local.md 中的任意一个文件，Claude Code 就不会读AGENTS.md。因此，AGENTS.md 只在两者都不存在时才生效。

另外，全局文件和 .claude/rules/ 的处理方式和项目文件不同。

• ~/.claude/CLAUDE.md
   是用户全局文件，任何情况下都会被读，不参与上面的判定，它的存在也不会让 AGENTS.md 失效。
• .claude/rules/
   是叠加的补充条目，本身不构成一份完整规范，能和任何一份主指令文件共存。

3. 三种典型用法

3.1 新项目，直接用 AGENTS.md

在项目根目录建 AGENTS.md，把规则写进去即可。同时不要建 CLAUDE.md 或 CLAUDE.local.md。

# 项目规范      ## 技术栈  Node.js 22 / TypeScript 5 / pnpm ## 代码约定- 使用两个空格缩进- 提交前必须执行 `pnpm lint`      ## 禁止事项- 不要直接修改 `src/generated/` 下的文件

3.2 项目已有 CLAUDE.md，想迁到 AGENTS.md

1. 把 CLAUDE.md 改名为  AGENTS.md。
2. 检查项目里有没有 CLAUDE.local.md，有就删掉，或者把内容合并进 AGENTS.md。
3. 检查 .claude/ 目录下有没有本地指令文件。
4. 不要当天验收，下一次会话才算数。

3.3 想让两份文件同时生效

把下面的配置写进 ~/.claude/settings.json：

{  ”pluginConfigs”: {    ”agents-md@builtin”: {      ”options”: {        ”instructionFiles”: ”claude-md-and-agents-md”      }    }  }  }

两份共存等于把“改两遍、忘一遍”的问题请回项目，建议只在其中一份是历史遗留时使用，长期还是收敛到一份。

4. 怎么确认它真的生效了

AGENTS.md 不会出现在 /memory 里，也不会出现在 /context 里，没有现成命令可查，只能自己放一个探针。

做法是在 AGENTS.md 里加一句唯一字符串，比如 PROBE-7731，然后新开一个会话问：

列出你的指令里包含的探针编号。

同时把能读文件的工具禁掉，否则模型会自己打开文件去抄，测出来的就不是加载结果：

回答里出现 PROBE-7731，说明文件被读到了；没有，说明没有。

5. 其他注意事项

• 平台限制。 Bedrock、Vertex、Foundry 环境不支持 AGENTS.md，禁用遥测的环境同样不可用。
• 全局文件始终生效。 ~/.claude/CLAUDE.md 不受项目判定影响。别把项目规则写在里面，那样只对写的人生效，别人看不到。
• 开 claude-md-and-agents-md 之前想清楚。 如果要两份都读，建议全团队一起开，否则同一个人读到新条款、另一个人没读到，从日志里看不出来。