【Bug已解决】Claude CLAUDE.md not loading / Project config ignored — Claude 项目配置不加载解决方案

【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. 原因分析

原因分类表

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. 各方案对比总结

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.json

5.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. 总结

1. 根本原因：配置不加载最常见原因是位置不对（35%）和文件名错误（25%）
2. 最佳实践：在项目根目录创建CLAUDE.md和.claude/settings.json
3. 文件名：使用CLAUDE.md（全大写），不是claude.md
4. 验证方法：claude --debug 2>&1 | grep -i "claude.md\|settings"确认配置加载
5. 最佳实践建议：在项目根目录启动 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[✅ 长期方案]