Claude Code 项目指令文件的读取优先级
文章称,Claude Code 自 v2.1.277 起支持 AGENTS.md,但启动目录及其上级存在指定的 Claude 指令文件时,默认会跳过它。可通过 @AGENTS.md 引用或调整项目指令配置,让两类文件共同生效。
AI 深度解读
Claude Code 已经能原生读取 AGENTS.md,但仓库里只要还留着某些 Claude 专用指令文件,这项支持就可能被关闭。作者给出的结论是:能识别文件名,不代表你的团队规则已经进入上下文。
这篇最有用的地方,是把版本门槛、文件优先级、团队迁移和重复计费串了起来。对于同时维护多种 AI 编程工具的团队,真正要解决的不是删掉一个文件,而是让每个人启动会话时,都能稳定读到同一份规则。
为什么有 AGENTS.md,Claude 却可能没读
作者依据 Anthropic 文档和 changelog 整理了这些行为,核对日期为 2026 年 11 月 22 日。这是文档梳理,原文没有提供独立实验记录。
从 Claude Code v2.1.277 开始,AGENTS.md 获得原生支持。但默认情况下,只要启动目录或任意上级目录存在 CLAUDE.md、.claude/CLAUDE.md、CLAUDE.local.md 中的一个,Claude 就会读取这些文件,跳过 AGENTS.md。
排查规则失效时,先检查启动目录和上级目录,比反复修改提示词更有用。
尤其容易踩坑的是 CLAUDE.local.md。它常被用于保存不提交的个人备注,却可能让依赖 AGENTS.md 的团队规则对你失效,而且没有报错。monorepo 根目录或仓库上方主目录里的 CLAUDE.md,也会触发相同行为。
不过,个人的 ~/.claude/CLAUDE.md、组织管理的 CLAUDE.md,以及 .claude/rules/ 文件不参与这个关闭判断,可以与 AGENTS.md 一起加载。AGENTS.local.md、Codex 使用的 AGENTS.override.md,以及 .agents/ 下的内容,则不在本文描述的读取范围内。
当原生读取生效时,启动目录向上的 AGENTS.md 和 .claude/AGENTS.md 会在启动时加载;子目录中的 AGENTS.md,要等 Claude 首次读取该目录里的文件时才加载,前提是子目录没有自己的 CLAUDE.md。文件里的 @path 导入也会展开。
规则有没有生效,既取决于文件名,也取决于启动位置和目录层级。
团队共用规则,保留导入通常更省事
如果希望两种文件同时读取,可以在 /config 的 Project instructions 中选择 claude-md-and-agents-md,也可以把下面的配置放进用户设置 ~/.claude/settings.json 或 managed settings:
{
"pluginConfigs": {
"cc-plugin-agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}
要注意 instructionFiles 这一行,以及配置所在的位置:Claude Code 会忽略项目设置和本地设置里的这项配置,因此不能靠提交仓库配置让全员启用。v2.1.285 之前的插件 ID 是 agents-md@builtin,后续版本接受两个 ID。
团队更容易统一的方案,是提交一个以 @AGENTS.md 开头的 CLAUDE.md。原文给出的形式如下,用来导入公共规则并保留 Claude 专属说明:
@AGENTS.md
## Claude Code only
- Hooks live in .claude/settings.json; don't duplicate their rules here.
关键是第一行的 @AGENTS.md。它是明确的文件导入;写一句「请阅读 AGENTS.md」,只是让模型自行决定是否打开文件,同时 CLAUDE.md 的存在又关闭了原生读取。
按照作者引用的文档,保留导入不会让同一个 AGENTS.md 被读取两遍。
如果坚持删除 CLAUDE.md,还要满足几项条件:所有人至少使用 v2.1.277;Amazon Bedrock 或关闭 telemetry 的会话至少需要 v2.1.281;没有个人文件、父目录文件阻断读取,或已开启同时读取。
此外,直接加载 AGENTS.md 不触发 InstructionsLoaded hooks,导入加载则会触发。通过 --add-dir 配合 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD 加载额外目录指令时,其 CLAUDE.md 能加载,AGENTS.md 不能。依赖这些机制的项目,不能只凭版本号决定迁移。
原生支持不会省 token,重复规则才会增加成本
启动时加载的指令,每次会话都要计入成本,发生在第一条用户提示之前。把 CLAUDE.md 换成 AGENTS.md,只是改变读取入口,不会让同样的文字更便宜。
开启 claude-md-and-agents-md 后,如果两个文件分别保存了一份相同规则,两份都会加载。Claude Code 会对同一文件的导入、符号链接和重复加载去重,但不会对不同文件中的重复段落去重。
共享规则只维护一份,既能减少重复上下文,也能减少指令冲突。
旧方案也该一起检查。SessionStart hook 如果仍在打印 AGENTS.md,原生加载生效后就会重复注入。CLAUDE.md 指向 AGENTS.md 的符号链接仍可使用并只加载一次;原文还说明,Edit 和 Write 工具会修改目标 AGENTS.md。但 Windows 克隆时若没有启用 core.symlinks,链接可能变成一行普通文本,导入方式更稳妥。
验证时应新开会话,检查启动提示 no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md,再运行 /memory 查看路径。v2.1.280 之前,/memory 和 /context 不显示直接读取的 AGENTS.md,作者建议询问 Claude 当前项目指令的内容。
仍未加载,就检查 claude --version,以及 /config 是否设为 claude-md 或 managed-only。配置项完全不存在时,作者建议使用导入。从 v2.1.276 或更早版本升级后的首次会话,还可能需要再开一次会话才生效。
我的判断
我赞成把 AGENTS.md 作为公共规则来源,再用很薄的 CLAUDE.md 接入。对版本混用、存在个人配置的团队,这比要求所有人修改用户设置更容易检查,也更方便代码审查。
但不能把「原生支持」理解为所有指令机制已经对齐。InstructionsLoaded、额外目录加载和子目录触发时机,都说明文件迁移涉及运行行为,不能只比较两份文本是否一致。
原文没有提供不同方案的 token 实测、任务成功率或故障率对照,因此不能据此断言哪种方式能提升编码质量。它提到的 Clogmeter 可以检查 token、重复和冲突,但没有展示检查结果。它的价值主要是提供配置排查依据,而非证明某种方案全面更优。
能拿来做什么
- 给前端或 Node 仓库整理指令时,把公共约定集中到 AGENTS.md,再通过 CLAUDE.md 的 @AGENTS.md 导入,避免维护两份相同正文。
- 团队成员反馈 AI 不遵守规则时,先记录启动目录、运行 claude --version,并检查父目录文件和 CLAUDE.local.md,再判断是否需要修改规则。
- monorepo 迁移前,分别验证根目录、子目录和 --add-dir 场景;依赖 InstructionsLoaded hooks 的流程,也要确认触发行为。
- 开启同时读取前,清理重复段落和 SessionStart 注入,再用新会话检查实际加载路径,避免只看仓库文件推断结果。