AI Tools
教程6 分钟2026年11月11日作者:AIGCDev

Claude Code 不遵守 CLAUDE.md?区分未加载与已加载后的排查方法

Claude Code 没按 CLAUDE.md 做事时,先不要假定文件没有加载:文件可能不在本次会话的加载范围内,也可能已经加载,但规则含糊、冲突,或者模型没有遵守。先看加载记录,再检查规则和实际行为,可以避免把不同问题混在一起。

本文面向本地 Claude Code 会话,依据截至 2026 年 11 月 11 日的官方记忆文档整理;命令和界面可能随版本变化。下面的诊断示例没有经过本站产品端到端实测,涉及模型的操作可能消耗你的额度。先在可丢弃的项目副本中操作,记录版本、启动目录、规则原文和观察结果,避免用真实项目的敏感内容做测试。

如果问题是 MCP 服务未连接或工具不可用,请参阅 Claude Code MCP 排障指南。

先确认该文件什么时候应该加载

在启动 Claude Code 的终端中确认当前目录和版本:

pwd
claude --version

项目级文件通常位于启动目录的 CLAUDE.md 或 .claude/CLAUDE.md;工作目录及其祖先目录的 CLAUDE.md、CLAUDE.local.md 在启动时加载。工作目录下的子目录文件则在 Claude 读取、写入或编辑该子目录内的其他文件时按需加载。多层文件的内容会合并进入上下文,并非后面的文件自动覆盖前面的文件。官方加载规则

在会话里输入 /context all,检查 Memory files 中应在启动时加载的文件路径。目标文件在列表中,继续检查内容和行为;缺失则核对启动目录、路径和下面的排除条件。/memory 可用来浏览和编辑记忆文件,但它的列表也包含尚不存在的文件位置,因此列在这里本身不能证明文件已加载。

如果目标在子目录,不要仅凭启动时列表缺失认定失败。先从 shell 创建或确认该目录里的 CLAUDE.md,然后在会话中让 Claude 读取该目录里的另一个文件;观察终端是否出现带目标路径的 Loaded 行。若仍未出现,核对实际访问路径、工作目录及排除设置。终端没有保留加载信息时,官方还提供 InstructionsLoaded hook 记录加载的文件、时间和原因;先阅读其适用范围再配置。

没加载:检查范围、排除和导入

确认路径存在只能证明文件在磁盘上,不能证明 Claude 已收到它。按实际情况检查:

  • 工作目录或 worktree 不同:重新确认会话启动位置,尤其是项目有多个 worktree 时。个人的 CLAUDE.local.md 可能只存在于其中一个 worktree。
  • 排除或启动选项:检查 claudeMdExcludes、启动参数中的 --setting-sources,以及会话 /config 中的 Project instructions;managed-only 会排除启动时的项目、本地和用户 CLAUDE.md,但子目录文件仍按需加载。不要为了诊断盲目覆盖组织管理的配置;参照设置范围与优先级检查实际生效的设置。
  • 额外目录:--add-dir 提供文件访问权限,默认不会加载该目录的 CLAUDE.md。若确实需要,按额外目录文档检查相应环境变量及限制。
  • @ 导入:相对路径相对于包含导入的文件解析;引用放在代码块或行内代码中不会触发导入。指向工作目录外的项目级导入首次需要批准,拒绝后不会加载。检查目标文件、导入写法和批准状态,而不是只检查主文件。导入规则
  • 文件过大:官方说明启动时加载的文件超过 4 MiB 会被跳过;按需加载文件另有更小的限制,见下文。启动时或 /status 的长度警告也值得检查,但超过推荐行数不等于整个文件未加载。

修改问题后,在相同启动目录开启新会话,再用相同的加载检查确认。若路径仍缺失,保留版本、启动方式、路径和相关设置,查阅官方排障文档,不要把磁盘上的文件当成加载成功。

已加载:检查冲突、长度和指令本身

列出本次适用的用户、项目、子目录指令及 .claude/rules/,对照当前任务找相互矛盾的要求。上下文顺序并不保证冲突按目录远近解决:官方说明冲突时 Claude 可能选择其中任一条。还要检查当次请求是否要求了与项目规则相反的行为。先由维护者确定正确规则,再删除或改写冲突内容;不要用猜测的优先级掩盖冲突。

将无法判断的要求改成可观察的动作。例如,下列是示意规则,须替换为项目真实约定:

修改 TypeScript 文件后,运行 bun run lint;如果无法运行,报告原因。

它比“保证代码质量”更容易核对:检查工具调用或终端记录是否运行了该命令,并核对失败原因,而不是只问 Claude 是否记住规则。若项目没有这个命令,就不要照搬。

官方建议每个 CLAUDE.md 尽量少于 200 行;这是编写建议,不是保证遵守的阈值。导入其他文件有助于组织,但导入内容仍进入上下文。对按需加载的子目录 CLAUDE.md 和路径规则,当前文档还规定单文件字符数上限,超出时只先提供开头并提示模型读取其余部分;上限随上下文窗口和模型变化,且 v2.1.309 之前不适用。用 wc -m path/to/CLAUDE.md 检查字符数,并按对应版本与上限判断;不要把文件路径出现在加载记录中等同于末尾规则已进入上下文。

只在长会话或压缩后出问题?

先记录问题发生在 /compact 前还是后,再对照同一条规则在新会话中的表现。官方说明压缩后项目根目录的 CLAUDE.md 会从磁盘重新读取并注入;子目录 CLAUDE.md 和带 paths 的规则则再次按需加载。只写在对话里的要求可能不在压缩后的上下文中。压缩后的说明

压缩后若子目录规则似乎失效,先让 Claude 读取该子目录内的相关文件,检查加载记录,再观察任务结果;路径规则则检查所访问的文件是否匹配其 paths。如果新会话和压缩后都能看到加载记录但行为不同,记录差异作为会话状态的线索,而非据此断言压缩是根因。

用实际行为确认,不只让模型复述

在隔离副本中选择一条低风险、结果可检查的规则和一个小任务。例如,规则要求修改后运行项目已有的 lint 命令,就让 Claude 做一处无敏感数据的小改动,再检查命令记录及退出结果。记录规则、提示词、版本、加载记录和实际动作;只改变一个条件重试,例如修正冲突后在新会话重复同一任务。示例是诊断方法,不是本站的测试结果。

  • 应加载的文件没有加载记录:回到路径、范围和排除设置。
  • 规则在按需文件的截断部分:先缩短文件或调整规则,再检查重新加载。
  • 规则已进入上下文但动作未发生:检查冲突与措辞;仍然失败时记录为该次未遵守,而不是证明文件未加载。一次成功或失败都不能证明长期可靠性。

CLAUDE.md 是提供给模型的上下文,不是强制执行机制。如果某个动作必须受到限制或在特定事件执行,应评估 permissions 和 hooks 等机制及其范围,并独立验证配置;不要把文字指令当成安全边界。

claude-codeai-codingtroubleshooting