调试 CLAUDE.md 失效：用 /context 排查配置加载问题

使用 /context 和 InstructionsLoaded hook，验证 CLAUDE.md 文件是否真的被加载。先解决延迟加载问题（嵌套文件、@imports），再修改规则措辞。只有确认规则已经进入上下文后，才重写规则。

你写了规则，Agent 却没有遵守。先别急着重写措辞——先检查这条规则是否真的进入了上下文窗口。根据我的经验，大多数“Claude 忽略了我的 CLAUDE.md”的问题，其实都是加载问题，而加载问题几秒钟就能检查清楚。

下面是我会依次执行的三项检查。

使用 /context 和 InstructionsLoaded hook，验证 CLAUDE.md 文件是否真的被加载。

先解决延迟加载问题（嵌套文件、@imports），再修改规则措辞。

只有确认规则已经进入上下文后，才重写规则。

1. /context——当前会话的真实依据

在当前会话中运行 /context，查看 Memory files 列表。这个列表展示的才是实际加载的内容——不是磁盘上存在什么，也不是理论上应该加载什么。如果你的文件不在其中，那么无论怎么调整 prompt 措辞都不会有用。

不要把它和 /memory 混淆。/memory 命令会列出用户级和项目级作用域内的 memory 文件位置——其中也包括尚不存在、可以由你创建的文件条目。它回答的是：“指令可以存放在哪里？”而 /context 回答的是：“Claude 此刻实际在读取什么？”调试时，只有第二个问题真正重要。

2. 了解两种延迟加载行为

几乎所有“我的规则消失了”的困惑，都来自下面两条加载规则。

嵌套的 CLAUDE.md 文件会按需加载。启动时，位于当前工作目录上级目录层级中的 CLAUDE.md 文件会被完整加载。但位于其下某个子目录中的 CLAUDE.md，只有在 Claude 实际读取该子目录树中的文件后才会加载。在会话早期，这条规则实际上并不存在——在第一次文件访问触发加载之前，/context 也会如实显示它尚未加载。如果一条规则必须始终生效，就应该把它放在根目录文件中，或者放进没有 path scope 的 .claude/rules/ 文件，而不是嵌套的 CLAUDE.md。

Imports 有不少容易踩坑的边界情况。@path/to/file imports 会在启动时与引用它们的文件一起加载，而且可以形成链式导入——但最多只能深入四跳。有两个细节经常让人中招：

Import 解析会跳过代码片段和围栏代码块。反引号中的 @README 是普通文本；反引号外的 @README 才是 import。如果你在“整理”文件时把 import 写进了代码围栏，就会在毫无提示的情况下禁用它。

相对路径是相对于包含该 import 的文件解析的，而不是相对于你的工作目录。如果某个片段导入了 ./shared.md，移动这个片段后，导入就会失效。

在真实项目中，我从来没有需要过两跳以上的导入（根文件导入 AGENTS.md，后者偶尔再导入一个共享片段）。如果你的导入链快接近四跳，通常真正需要修复的就是这条链本身。

3. InstructionsLoaded——实时记录每一次加载

你不可能在每次访问文件后都守在会话里运行 /context，因此 Claude Code 专门提供了对应的 hook 事件：每当一个 CLAUDE.md 或 .claude/rules/*.md 文件进入上下文时，InstructionsLoaded 都会触发。对于立即加载的文件，它会在会话开始时触发；当嵌套文件或具有 path scope 的规则延迟加载时，它还会在会话中途再次触发。

hook 输入会告诉你三项信息：file_path（哪个文件）、memory_type（User / Project / Local / Managed）和 load_reason。其中最值得关注的是 load_reason，它可能包含以下值：

session_start——启动时立即加载

nested_traversal——某个子目录中的 CLAUDE.md 刚刚被延迟加载

path_glob_match——一条具有 path scope 的规则匹配到了 Claude 访问的文件

include——通过 @path import 引入

compact——上下文压缩后重新加载

在 .claude/settings.json 中添加一个最简日志记录器：

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\(.load_reason)\t\(.file_path)\"' >> ~/.claude/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

现在，tail -f ~/.claude/instructions-loaded.log 会显示嵌套的 CLAUDE.md 究竟在何时进入上下文——不用再等到三个 prompt 之后观察到行为变化，才反过来猜测它是什么时候加载的。这个 hook 只用于可观测性（它会异步运行，退出码也会被忽略），所以不会破坏任何功能。

你还可以根据加载原因使用 matcher 进行过滤，例如设置 "matcher": "nested_traversal|path_glob_match"，只记录延迟加载事件。

30 秒调试流程

规则被忽略了？运行 /context。如果文件没有出现在 Memory files 中 → 这是加载问题，停止修改措辞。

文件嵌套在子目录中 → 这是预期行为：只有 Claude 读取该子目录树后，它才会加载。如果它必须始终生效，就把它移到根目录。

文件通过 import 引入 → 检查 import 是否被写在反引号或代码围栏中，检查相对于导入方文件的相对路径，并计算导入跳数（最多四跳）。

文件已经加载，但行为仍然不对 → 现在才是指令质量问题。重写规则，让它更加具体；检查是否存在相互矛盾的规则；并将文件控制在约 200 行以内。

只有第 4 步属于 prompt engineering 问题。第 1～3 步都是机械式检查，而 InstructionsLoaded 日志能让这些检查从猜测变成一次 grep。

关于完整的解析顺序——哪些文件会被加载、按什么顺序加载，以及发生冲突时谁会胜出——我已经在《Claude Code 实际会加载哪些 CLAUDE.md 文件（以及加载顺序）》中进行了详细说明。

最初发布于 gentic.news。

如果需要采取进一步措施，你可以考虑屏蔽此人和/或举报滥用行为。