【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. 原因分析原因分类表原因分类具体表现占比位置不对不在根目录约 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 21 | 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 21 | 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 21 | 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, indent2) # 步骤 3项目级优先 # 项目级 .claude/settings.json 用户级 ~/.claude/settings.json # 步骤 4验证 claude --debug 21 | 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 21 | grep -i claude.md4. 各方案对比总结方案适用场景推荐指数难度方案一检查位置通用⭐⭐⭐⭐⭐低方案二创建配置无配置⭐⭐⭐⭐⭐低方案三根目录路径⭐⭐⭐⭐⭐低方案四JSON 格式语法⭐⭐⭐⭐⭐低方案五优先级冲突⭐⭐⭐⭐⭐低方案六更新版本⭐⭐⭐低5. 常见问题 FAQ5.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 21 | grep -i claude.md\|settings\|config5.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 21 | 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[✅ 长期方案]