【Bug已解决】Claude: "CLAUDE.md not loading" / Project config ignored — Claude 项目配置不加载解决方案
1. 问题描述
Claude Code 无法加载项目级配置文件 CLAUDE.md 或 .claude/settings.json：
# CLAUDE.md 不加载 $ cat CLAUDE.md # 项目指令... $ claude "task" # Claude 忽略了 CLAUDE.md 中的指令 # 或 settings.json 不生效 $ cat .claude/settings.json {"model": "claude-sonnet-4-20250514"} $ claude "task" # 使用默认模型，未使用配置中的模型 # 或权限配置不生效 $ cat .claude/settings.json {"allowedTools": ["Read", "Write"]} $ claude --auto-approve "task" # 仍然提示权限审批 # 或 CLAUDE.md 在子目录不加载 $ cd src && claude # 找不到 /project/CLAUDE.md这个问题在以下场景中特别常见：
- CLAUDE.md 位置不对
- 文件名拼写错误
- 工作目录不对
- 配置 JSON 格式错误
- 优先级冲突
- 版本不支持
2. 原因分析
原因分类表
| 原因分类 | 具体表现 | 占比 |
|---|---|---|
| 位置不对 | 不在根目录 | 约 35% |
| 文件名错误 | claude.md/CLAUDE.txt | 约 25% |
| 工作目录 | 子目录启动 | 约 15% |
| JSON 格式错误 | 语法 | 约 10% |
| 优先级冲突 | 用户级覆盖 | 约 10% |
| 版本不支持 | 旧版本 | 约 5% |
3. 解决方案
方案一：检查文件位置和名称（最推荐）
# 步骤 1：检查 CLAUDE.md 位置 ls -la CLAUDE.md # 必须在项目根目录 # 步骤 2：检查文件名（大小写） # 正确: CLAUDE.md # 错误: claude.md, CLAUDE.txt, Claude.md # 步骤 3：检查 .claude/settings.json ls -la .claude/settings.json # 步骤 4：验证加载 claude --debug 2>&1 | grep -i "claude.md\|config\|settings"方案二：在根目录创建配置
# 步骤 1：在项目根目录创建 CLAUDE.md cat > CLAUDE.md << 'EOF' # 项目指令 ## 代码规范 - 使用 Python 3.12 - 遵循 PEP 8 ## 文件结构 - src/: 源代码 - tests/: 测试 EOF # 步骤 2：创建 .claude/settings.json mkdir -p .claude cat > .claude/settings.json << 'EOF' { "model": "claude-sonnet-4-20250514", "allowedTools": ["Read", "Write", "Edit", "Bash"] } EOF # 步骤 3：验证 claude --debug 2>&1 | grep -i "claude.md\|settings"方案三：在根目录启动
# 步骤 1：切换到项目根目录 cd /project claude "task" # 步骤 2：不要在子目录启动 # 错误: cd /project/src && claude # 正确: cd /project && claude # 步骤 3：或指定工作目录 claude --working-dir /project "task" # 步骤 4：验证 claude --debug 2>&1 | grep -i "working\|root"方案四：验证 JSON 格式
# 步骤 1：验证 JSON python3 -m json.tool .claude/settings.json # 步骤 2：如果报错，修复 # 常见: 尾逗号、注释、单引号 # 步骤 3：重新创建 cat > .claude/settings.json << 'EOF' { "model": "claude-sonnet-4-20250514", "allowedTools": ["Read", "Write", "Edit", "Bash"] } EOF # 步骤 4：验证 python3 -m json.tool .claude/settings.json claude "task"方案五：检查优先级
# 步骤 1：检查用户级配置 cat ~/.claude/settings.json # 步骤 2：如果用户级覆盖项目级 # 删除用户级中的冲突配置 python3 -c " import json with open('/root/.claude/settings.json') as f: config = json.load(f) config.pop('model', None) with open('/root/.claude/settings.json', 'w') as f: json.dump(config, f, indent=2) " # 步骤 3：项目级优先 # 项目级 .claude/settings.json > 用户级 ~/.claude/settings.json # 步骤 4：验证 claude --debug 2>&1 | grep -i "model\|settings"方案六：更新版本
# 步骤 1：检查版本 claude --version # 步骤 2：更新 npm update -g @anthropic-ai/claude-code # 步骤 3：验证 CLAUDE.md 支持 claude --help | grep -i "claude.md\|config" # 步骤 4：测试 claude "task" claude --debug 2>&1 | grep -i "claude.md"4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一：检查位置 | 通用 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二：创建配置 | 无配置 | ⭐⭐⭐⭐⭐ | 低 |
| 方案三：根目录 | 路径 | ⭐⭐⭐⭐⭐ | 低 |
| 方案四：JSON 格式 | 语法 | ⭐⭐⭐⭐⭐ | 低 |
| 方案五：优先级 | 冲突 | ⭐⭐⭐⭐⭐ | 低 |
| 方案六：更新 | 版本 | ⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.1 CLAUDE.md 放在哪里
项目根目录/project/CLAUDE.md。
5.2 文件名大小写重要吗
是的。使用CLAUDE.md（全大写），不是claude.md。
5.3 .claude/settings.json 在哪里
/project/.claude/settings.json（项目根目录下的 .claude 文件夹）。
5.4 如何验证配置加载
claude --debug 2>&1 | grep -i "claude.md\|settings\|config"5.5 用户级和项目级的优先级
项目级.claude/settings.json> 用户级~/.claude/settings.json。
5.6 在子目录启动找不到 CLAUDE.md
在项目根目录启动，或使用--working-dir /project。
5.7 CLAUDE.md 支持什么
Markdown 格式的项目指令，Claude 会自动读取并遵循。
5.8 settings.json 支持哪些配置
model、allowedTools、sandbox、toolTimeout 等。
5.9 如何检查 JSON 格式
python3 -m json.tool .claude/settings.json5.10 排查清单速查表
□ 1. ls CLAUDE.md 确认在根目录 □ 2. 文件名: CLAUDE.md（大写） □ 3. ls .claude/settings.json 确认 □ 4. python3 -m json.tool 验证 JSON □ 5. cd /project 根目录启动 □ 6. claude --debug | grep config 验证 □ 7. 检查 ~/.claude/settings.json 优先级 □ 8. 删除用户级冲突配置 □ 9. npm update 更新 Claude Code □ 10. --working-dir 指定目录6. 总结
- 根本原因：配置不加载最常见原因是位置不对（35%）和文件名错误（25%）
- 最佳实践：在项目根目录创建
CLAUDE.md和.claude/settings.json - 文件名：使用
CLAUDE.md（全大写），不是claude.md - 验证方法：
claude --debug 2>&1 | grep -i "claude.md\|settings"确认配置加载 - 最佳实践建议：在项目根目录启动 Claude，使用
python3 -m json.tool验证 JSON 格式
故障排查流程图
flowchart TD A[配置不加载] --> B[ls CLAUDE.md 检查] B --> C{文件存在?} C -->|否| D[在根目录创建 CLAUDE.md] C -->|是| E{文件名正确?} D --> F[cat > CLAUDE.md << EOF] F --> G[claude --debug | grep config] E -->|否, 小写| H[改为 CLAUDE.md] E -->|是| I[在根目录启动] H --> G I --> j[cd /project && claude] j --> G G --> K{配置加载?} K -->|是| L[✅ 问题解决] K -->|否| M[检查 JSON 格式] M --> N[python3 -m json.tool settings.json] N --> O{JSON 有效?} O -->|否| P[修复 JSON 格式] O -->|是| Q[检查优先级冲突] P --> G Q --> R[cat ~/.claude/settings.json] R --> S{用户级覆盖?} S -->|是| T[删除用户级冲突配置] S -->|否| U[更新版本] T --> G U --> V[npm update -g claude-code] V --> G G --> W{成功?} W -->|是| L W -->|否| X[--working-dir 指定] X --> Y[claude --working-dir /project] Y --> L L --> Z[长期: 根目录 + CLAUDE.md + settings.json] Z --> AA[✅ 长期方案]
)
