Claude Code 配置不生效时的诊断速查：核心命令矩阵 + 12+ 常见错误根因表，覆盖 hook/skill/permission/MCP/CLAUDE.md 排查路径
5 分钟
当 Claude 忽略某条指令或配置的功能没有出现时，原因通常是文件未加载、从非预期位置加载、或被另一个文件覆盖。运行时错误见 运行时错误速查。
一、核心诊断命令矩阵
先运行 /context 获取全局概览，再用专项命令定位具体问题。
| 命令 | 显示内容 | 用途 |
|---|---|---|
/context | 占据上下文窗口的所有内容：system prompt、记忆文件、Skill、MCP 工具、对话消息 | 确认 CLAUDE.md / rules / skill descriptions 是否存在 |
/memory | 已加载的 CLAUDE.md 和 rules 文件列表 + Auto-Memory 条目 | 定位缺失的记忆文件 |
/skills | 可用 Skill（项目 / 用户 / Plugin 来源）。按 t 按 Token 数排序 | 确认 Skill 是否注册 |
/agents | 已配置的 SubAgent 及其设置 | 确认 Agent 定义 |
/hooks | 当前会话注册的 Hook，按事件分组 | 确认 Hook 是否被读取 |
/mcp | 已连接 MCP 服务器及其状态 | 确认服务器连接和工具数 |
/permissions | 当前生效的 allow / deny 规则 | 确认权限生效范围 |
/doctor | 配置诊断：无效 key、schema 错误、安装健康 | 发现配置格式问题 |
/status | 活跃的 settings 来源（含是否有 managed settings） | ��认哪个层级的设置在生效 |
二、常见错误根因表
| 症状 | 原因 | 修复 |
|---|---|---|
| Hook never fires | matcher 是 JSON 数组而非字符串 | 用单个字符串 + | 分隔，如 "Edit|Write"。详见 Hooks matcher |
| Hook never fires | matcher 值小写（如 "bash"） | 工具名区分大小写：Bash、Edit、Write、Read |
| Hook never fires | Hook 写在独立文件 .claude/hooks.json 中 | 没有独立 hooks 文件。在 settings.json 的 "hooks" key 下定义 |
| 全局 permissions/hooks/env 被忽略 | 配置加到了 ~/.claude.json | ~/.claude.json 存放应用状态和 UI 开关。permissions/hooks/env 属于 ~/.claude/settings.json。两个不同文件 |
| settings.json 值似乎被忽略 | 同一 key 在 settings.local.json 中也设置了 | settings.local.json 覆盖 settings.json，两者都覆盖 ~/.claude/settings.json。详见 设置优先级 |
Skill 不出现在 /skills 中 | Skill 文件直接放在 .claude/skills/name.md | 需使用文件夹结构：.claude/skills/name/SKILL.md |
| Skill 出现但 Claude 不调用 | frontmatter 有 disable-model-invocation: true；或 description 与请求措辞不匹配 | /skills ��带 "user-only" 标记的 Skill 不会被 Claude 自动触发 |
| 子目录 CLAUDE.md 被忽略 | 子目录文件按需加载，不在启动时加载 | 仅当 Claude 用 Read 工具读取该目录下的文件时才加载。不是启动时、也不是写入文件时 |
| SubAgent 忽略 CLAUDE.md 指令 | SubAgent 不总是继承项目记忆 | 将关键规则写入 agent 文件 body（成为 SubAgent 的 system prompt）。详见 自定义 SubAgent |
| MCP 服务器不加载 | .mcp.json 放在 .claude/ 下或使用了 Claude Desktop 格式 | ���目 MCP 配置放在仓库根目录的 .mcp.json，不在 .claude/ 内 |
| 项目 MCP 服务器已添加但不出现 | 一次性审批提示被关闭 | 项目级服务器需审批。运行 /mcp 查看状态并审批 |
| MCP 服务器从某些目录启动失败 | command 或 args 使用了相对路径 | 用绝对路径。npx/uvx 等 PATH 上的可执行文件无需修改 |
| MCP 服务器启动但缺少环境变量 | 变量在 settings.json 的 env 中，不传播到 MCP 子进程 | 在 .mcp.json 中为每个服务器设置 env |
Bash(rm *) deny 规则未阻止 /bin/rm | 前缀规则匹配字面命令字符串，不匹配底层可执行文件 | 为每个变体添加显式 pattern，或用 PreToolUse hook 或 sandbox 做硬保证 |
| 会话结束时清理逻辑不运行 | 未配置 SessionEnd hook | 在 settings.json 中添加 SessionEnd hook |
三、CLAUDE.md 指令不被遵守
/memory 确认文件已加载但 Claude 仍不遵守某条指令时，问题通常在指令写法而非加载：
- 模糊性：指令有多种解读方式时遵守率下降
- 冲突：两个文件给出矛盾指令
- 长度：文件过长时单条规则得到的关注减少。推荐长度 200 行以内
CLAUDE.md vs 权限
CLAUDE.md 告诉 Claude 项目如何运作，是指导性的。权限和 Hook 强制执行限制，不管 Claude 决定什么。安全边界和绝对禁止的操作用权限或 Hook，不用 CLAUDE.md。
四、Settings 层级冲突
Settings 从 managed、user、project、local 四个范围合并。Managed settings（管理员控制台）始终优先。其余按 local → project → user 顺序覆盖。CLI flag 和环境变量是额外的覆盖层。
排查方法：
/doctor验证配置文件（无效 key、schema 错误）/status查看活��的 settings 来源- 查看 设置优先级 确认哪个范围胜出
五、/heapdump 内存诊断
高内存使用时运行 /heapdump，生成 JavaScript 堆快照和内存分解写入 ~/Desktop（Linux 无 Desktop 文件夹时写 home 目录���。用 Chrome DevTools 的 Memory 面板打开 .heapsnapshot 文件分析。
六、Auto-compaction thrashing
如果 auto-compact 频繁触发导致信息丢失（"thrashing"），排查：
/context��看窗口消耗- 大量 MCP 工具定义可能在每次 compact 后立即重新填满窗口
/mcp disable+ 服务器名 禁用不用的 MCP 服务器- 精简过大的 CLAUDE.md 或移入路径条件规则
PreCompact hook 可阻断自动压缩：{"decision":"block"} �� exit code 2。
七、关联资源
| 资源 | 说明 |
|---|---|
.claude 目录参考 | 所有配置文件位置 |
| Settings 参考 | 优先级和完整 key 列表 |
| Hooks 参考 | 事件名、payload 和 --debug hooks 输出 |
| MCP 参考 | 服务器配置和 /mcp 输出 |
| 运行时错误速查 | API/配额/鉴权/网络错误 |