# 配置调试与 .claude 目录

> 排查 CLAUDE.md、settings、Hooks、MCP、Skills、权限、.claude 目录、数据流和本地数据清理。

URL: https://docs.passion8.cc/docs/claude-code/configuration-debugging
Language: zh-CN
Publisher: Passion8

当 Claude Code 忽略某条规则、Hook 不触发、MCP 不出现、Skill 不可用或 settings 不生效时,不要猜。先看 Claude Code 实际加载了什么。

## 一组命令先定位

| 命令 | 看什么 |
| --- | --- |
| `/context` | 当前上下文里的系统提示、记忆、skills、subagents、MCP、消息 |
| `/memory` | 哪些 `CLAUDE.md`、rules 和 auto memory 被加载 |
| `/skills` | 项目、用户、插件来源的 skills |
| `/hooks` | 当前会话注册的 hook 和事件 |
| `/mcp` | MCP server、连接状态、approval 状态 |
| `/permissions` | 当前 allow/ask/deny 规则来源 |
| `/doctor` | 配置 schema、安装状态、重复 subagent 名称等诊断 |
| `/status` | 当前 settings 来源、managed policy、登录和模型状态 |
| `/debug <问题>` | 开启调试日志并让 Claude 协助分析 |

## 配置文件位置

| 文件 | 作用 | 是否适合提交 |
| --- | --- | --- |
| `CLAUDE.md` | 项目记忆,团队约定,常用命令 | 可提交 |
| `.claude/CLAUDE.md` | 项目级补充记忆 | 可提交 |
| `.claude/settings.json` | 团队共享 settings、permissions、hooks | 可提交,不要放 Key |
| `.claude/settings.local.json` | 本项目个人覆盖 | 不提交 |
| `~/.claude/settings.json` | 用户级偏好、个人 env、通用权限 | 不提交 |
| `.mcp.json` | 项目 MCP server | 可提交,敏感值用 env |
| `~/.claude.json` | app 状态、登录、项目状态和部分 MCP 本地数据 | 不手写业务配置 |
| `.claude/commands/` | 自定义斜杠命令 | 可提交 |
| `.claude/skills/<name>/SKILL.md` | 项目 skill | 可提交 |
| `.claude/agents/` | 自定义 subagent | 可提交 |
| `.claude/output-styles/` | 输出风格 | 可提交或用户级 |




`~/.claude.json` 不是 settings 文件。`permissions`、`hooks`、`env` 应写进 `settings.json`,不是写进 `~/.claude.json`。




## settings 合并和覆盖

常规优先级:

1. Managed policy
2. 命令行参数和部分环境变量
3. `.claude/settings.local.json`
4. `.claude/settings.json`
5. `~/.claude/settings.json`

权限规则会合并。冲突时按 `deny`、`ask`、`allow` 处理,不是简单覆盖。

常见误解:

| 现象 | 原因 | 修复 |
| --- | --- | --- |
| 用户级设置不生效 | 项目 local 覆盖了同名 key | `/status` 看来源 |
| Hook 不出现 | 写到独立 hook 文件或 `~/.claude.json` | 写进 settings 的 `hooks` key |
| MCP 不出现 | `.mcp.json` 放到了 `.claude/` 里 | 项目 MCP 放仓库根目录 |
| env 没传给 MCP | settings 的 `env` 不等于 MCP 子进程 env | 在 `.mcp.json` server 内写 `env` |
| skill 不出现 | 文件路径是 `.claude/skills/name.md` | 应为 `.claude/skills/name/SKILL.md` |
| subdir `CLAUDE.md` 没加载 | 子目录记忆按需加载 | 让 Claude Read 该目录文件 |

## CLAUDE.md 不生效

先看:

```text
/memory
/context all
```

如果文件没出现,检查位置和启动目录。如果文件出现但执行不好,通常是规则写得太泛、互相冲突或文件太长。

更稳的写法:

- 写具体命令,不要只写“运行测试”。
- 写目录归属,例如“React 组件在 `src/components`”。
- 把安全边界交给 permissions 或 Hooks,不要只靠自然语言。
- 大型仓库按目录拆 `CLAUDE.md`,避免根文件变成百科。

## Hooks 不触发

检查:

```text
/hooks
claude --debug hooks
```

| 现象 | 可能原因 |
| --- | --- |
| `/hooks` 看不到 | settings 文件没加载或 key 写错 |
| matcher 不命中 | 工具名大小写错误,例如应为 `Bash`、`Edit`、`Write` |
| 多工具 matcher 写错 | 用单个字符串,例如 `Edit|Write` |
| schema error | `/doctor` 会报告,该 hook 会被丢弃 |
| 命令路径不稳定 | 用 `${CLAUDE_PROJECT_DIR}` 或绝对路径 |
| 退出码无效 | 按事件要求返回 JSON 或 stderr |

## MCP 不出现

检查:

```bash
claude mcp list
claude mcp get <name>
claude --debug mcp
```

| 现象 | 处理 |
| --- | --- |
| Project server pending approval | 打开 `/mcp` 批准 |
| server failed | 看 stderr,检查 command、args、env |
| connected 但零工具 | Reconnect,再看 debug 输出 |
| OAuth 失败 | `claude mcp login <name>` |
| 相对路径在某些目录失败 | 改绝对路径 |
| 工具太多影响缓存 | 结合 tool search 或拆 server |

## 干净配置对照

`--safe-mode` 会禁用大多数自定义项:

```bash
claude --safe-mode
```

如果问题消失,通常来自 `CLAUDE.md`、skills、plugins、hooks、MCP、自定义命令、agents、output styles 或 workflows。

完全干净配置:

```bash
mkdir -p /tmp/claude-clean
cd /tmp
CLAUDE_CONFIG_DIR=/tmp/claude-clean claude
```

说明:

- Managed policy 仍可能生效。
- macOS 登录凭据可能在 Keychain,不一定被 `CLAUDE_CONFIG_DIR` 隔离。
- Linux/Windows 可能需要重新登录。

## .claude 目录怎么用

推荐结构:

```text
.claude/
  settings.json
  settings.local.json
  commands/
    review.md
  skills/
    release-check/
      SKILL.md
  agents/
    qa-reviewer.md
  output-styles/
    concise.md
```

不要把这些放错:

| 不建议 | 原因 |
| --- | --- |
| `.claude/.mcp.json` | 项目 MCP 应在仓库根目录 `.mcp.json` |
| `.claude/skills/foo.md` | skill 需要文件夹和 `SKILL.md` |
| `.claude/hooks.json` | 普通 hooks 属于 settings,插件才有独立 hooks 文件 |
| `.claude/settings.json` 写真实 Key | 项目文件容易提交泄露 |

## 数据使用和本地数据

Claude Code 会把完成任务所需的 prompt、工具结果、文件片段、MCP 输出等发送给所选 provider。接 Passion8 时,还要看 Passion8 网关的日志、计费和保留策略。

| 类型 | 位置或流向 | 注意 |
| --- | --- | --- |
| 本地项目文件 | 工具读取后进入模型上下文 | 用 permissions 和 Hooks 控制敏感路径 |
| 用户设置和状态 | `~/.claude/`、`~/.claude.json` 等 | 不要提交 |
| shell 命令输出 | 进入当前会话上下文 | 避免打印密钥和大日志 |
| MCP 工具输出 | 进入当前会话上下文 | 给数据库、浏览器 MCP 做过滤 |
| Telemetry | 由 OTel 环境变量控制 | 默认谨慎,不要记录 raw API body |
| WebFetch 域名检查 | 可能走安全检查 | 企业网络需考虑出站域名 |

更严格的项目建议:

- `Read(./.env)`、`Read(./.env.*)` 放 deny。
- 对 `curl`、`wget`、数据库写操作加 ask 或 Hook。
- 不在 Hook stderr 输出完整密钥。
- 监控只采集必要字段,不要开启 `OTEL_LOG_RAW_API_BODIES`。

## 缓存影响

配置调试常会改变 prompt 前缀:

| 动作 | 5m/1h 缓存影响 |
| --- | --- |
| 改 `CLAUDE.md` 后新会话 | 前缀变,通常重新写缓存 |
| 改 permissions | 通常影响较小,但工具可用性变化会影响前缀 |
| 增删 MCP server | 工具 schema 变化,常导致 miss |
| 增删 skills/plugins | 系统提示和工具可能变化 |
| `--safe-mode` | 与正常会话前缀不同,不要用它评估命中率 |
| `CLAUDE_CONFIG_DIR` 干净测试 | 适合排错,不代表真实项目缓存表现 |

## 官方参考

- [Debug your configuration](https://code.claude.com/docs/en/debug-your-config.md)
- [Explore the .claude directory](https://code.claude.com/docs/en/claude-directory.md)
- [Data usage](https://code.claude.com/docs/en/data-usage.md)
- [Settings](https://code.claude.com/docs/en/settings.md)
- [MCP](https://code.claude.com/docs/en/mcp.md)