配置调试与 .claude 目录

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

#一组命令先定位

#配置文件位置

#settings 合并和覆盖

常规优先级:

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

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

常见误解:

#CLAUDE.md 不生效

先看:

/memory
/context all

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

更稳的写法:

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

#Hooks 不触发

检查:

/hooks
claude --debug hooks

#MCP 不出现

检查:

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

#干净配置对照

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

claude --safe-mode

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

完全干净配置:

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

说明:

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

#.claude 目录怎么用

推荐结构:

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

不要把这些放错:

#数据使用和本地数据

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

更严格的项目建议:

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

#缓存影响

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

#官方参考

• Debug your configuration
• Explore the .claude directory
• Data usage
• Settings
• MCP