【Bug已解决】CLAUDE.md not loaded / Project instructions ignored — Claude Code 项目指令未加载解决方案1. 问题描述创建了 CLAUDE.md 文件包含项目规范但 Claude Code 似乎没有读取或遵循# CLAUDE.md 存在但不生效 $ cat .claude/CLAUDE.md # 使用 4 空格缩进 # 不要使用 var 关键字 # 测试使用 vitest $ claude 创建一个新函数 # Claude Code 生成的代码使用了 2 空格缩进和 var 关键字 # CLAUDE.md 中的规范被忽略或者# CLAUDE.md 中的禁令不生效 $ cat CLAUDE.md # 禁止修改 src/config.js $ claude 修改配置文件 # Claude Code 修改了 src/config.js # 禁令被忽略这个问题在以下场景中特别常见CLAUDE.md 放置位置不正确CLAUDE.md 文件名拼写错误文件编码不是 UTF-8CLAUDE.md 内容过长被截断项目级和用户级 CLAUDE.md 冲突/clear 后 CLAUDE.md 需要重新加载2. 原因分析核心原理拆解Claude Code 启动 → 查找 CLAUDE.md ↓ 文件不存在/位置错误/编码问题 ↓ CLAUDE.md 内容未加载到系统提示 ↓ 项目指令被忽略原因分类表原因分类具体表现占比位置错误不在 .claude/ 目录约 35%文件名错误拼写错误或大小写约 25%编码问题非 UTF-8约 15%内容过长超过 Token 限制被截断约 10%/clear 后需要重新加载约 10%配置覆盖项目级被用户级覆盖约 5%3. 解决方案方案一放置在正确位置最推荐# 步骤 1确认 CLAUDE.md 的正确位置 # 项目级: .claude/CLAUDE.md 或项目根目录 CLAUDE.md # 用户级: ~/.claude/CLAUDE.md # 步骤 2检查文件是否存在 ls -la .claude/CLAUDE.md ls -la CLAUDE.md # 步骤 3如果不存在创建 mkdir -p .claude cat .claude/CLAUDE.md EOF # 项目规范 ## 代码风格 - 使用 4 空格缩进 - 使用 const/let不使用 var - 使用单引号 ## 测试 - 使用 vitest - 测试文件放在 tests/ 目录 ## 禁止操作 - 不要修改 src/config.js - 不要修改 .env 文件 EOF # 步骤 4验证 claude --debug 21 | grep -i claude.md\|instruction\|system方案二检查文件名和大小写# 步骤 1确认文件名正确 # 正确: CLAUDE.md全大写 # 错误: claude.md, Claude.md, CLAUDE.MD ls -la .claude/CLAUDE.md # 如果不存在 mv .claude/claude.md .claude/CLAUDE.md # 步骤 2或检查项目根目录 ls -la CLAUDE.md # 步骤 3Claude Code 会同时查找 .claude/CLAUDE.md 和 ./CLAUDE.md方案三验证文件编码# 步骤 1检查文件编码 file .claude/CLAUDE.md # 应该输出: UTF-8 Unicode text 或 ASCII text # 步骤 2如果不是 UTF-8 iconv -f GBK -t UTF-8 .claude/CLAUDE.md .claude/CLAUDE.md.utf8 mv .claude/CLAUDE.md.utf8 .claude/CLAUDE.md # 步骤 3验证 file .claude/CLAUDE.md方案四控制 CLAUDE.md 长度# 步骤 1检查文件大小 wc -c .claude/CLAUDE.md wc -w .claude/CLAUDE.md # 步骤 2建议控制在 1000 字以内约 1500 tokens # 如果过长精简内容 # 步骤 3将详细规范拆分到单独文件 # CLAUDE.md 只保留核心规范 # 详细规范放在 docs/coding-standards.md 中 # CLAUDE.md 中引用: 详细规范见 docs/coding-standards.md # 步骤 4使用 --debug 验证加载 claude --debug 21 | grep CLAUDE方案五/clear 后重新加载# 步骤 1/clear 会清空上下文 /clear # CLAUDE.md 需要重新加载 # 步骤 2重新引用 请参考 CLAUDE.md 中的项目规范 # 步骤 3或重新启动 /exit claude # 启动时会自动加载 CLAUDE.md # 步骤 4验证 你知道项目的代码规范吗 # Claude 应该能回答 CLAUDE.md 中的内容方案六使用 .claude/settings.json 补充配置# 步骤 1有些配置需要放在 settings.json 而非 CLAUDE.md cat .claude/settings.json EOF { allowedTools: [Read, Write, Edit, Bash], blockedCommands: [rm -rf, git push --force] } EOF # 步骤 2CLAUDE.md 放行为规范 # settings.json 放技术配置 # 步骤 3两者配合使用4. 各方案对比总结方案适用场景推荐指数难度方案一正确位置通用方案⭐⭐⭐⭐⭐低方案二文件名拼写问题⭐⭐⭐⭐⭐低方案三编码修复非 UTF-8⭐⭐⭐⭐低方案四控制长度内容过长⭐⭐⭐⭐⭐低方案五/clear 后上下文清空⭐⭐⭐⭐低方案六settings.json技术配置⭐⭐⭐⭐低5. 常见问题 FAQ5.1 CLAUDE.md 应该放在哪里两个位置都可以.claude/CLAUDE.md— Claude Code 专用目录CLAUDE.md— 项目根目录 Claude Code 会自动查找这两个位置。5.2 项目级和用户级 CLAUDE.md 的优先级两者都会加载。用户级~/.claude/CLAUDE.md是全局规范项目级是项目特定规范。项目级不会覆盖用户级两者叠加。5.3 CLAUDE.md 支持什么格式标准 Markdown 格式。支持标题、列表、代码块、表格等。5.4 CLAUDE.md 多大合适建议控制在 1000 字以内约 1500 tokens。过长的 CLAUDE.md 会占用上下文空间。将详细规范拆分到单独文件。5.5 如何验证 CLAUDE.md 已加载claude --debug 21 | grep -i claude.md # 或直接询问 你知道项目的代码规范吗5.6 /compact 会丢失 CLAUDE.md 吗不会。CLAUDE.md 是系统提示的一部分/compact只压缩对话历史不压缩系统提示。5.7 /clear 会丢失 CLAUDE.md 吗/clear清空上下文但 CLAUDE.md 应该在清空后重新加载。如果没有重启 Claude Code。5.8 多个项目的 CLAUDE.md每个项目的.claude/CLAUDE.md独立。切换项目时加载对应的 CLAUDE.md。5.9 CLAUDE.md 中可以放命令吗可以放示例命令在代码块中但 Claude Code 不会自动执行。Claude Code 会读取并遵循其中的指令。5.10 排查清单速查表□ 1. 确认 .claude/CLAUDE.md 或 CLAUDE.md 存在 □ 2. 文件名全大写: CLAUDE.md □ 3. file 命令检查编码为 UTF-8 □ 4. 内容控制在 1000 字以内 □ 5. claude --debug 验证加载 □ 6. 询问 Claude 是否知道规范 □ 7. /clear 后重启验证重新加载 □ 8. 项目级和用户级配合使用 □ 9. 技术配置放 settings.json □ 10. 行为规范放 CLAUDE.md6. 总结根本原因CLAUDE.md 未加载最常见原因是位置错误35%不在 .claude/ 目录和文件名拼写错误25%最佳实践将 CLAUDE.md 放在.claude/CLAUDE.md或项目根目录文件名全大写使用 UTF-8 编码内容控制CLAUDE.md 控制在 1000 字以内将详细规范拆分到docs/目录在 CLAUDE.md 中引用验证方法使用claude --debug 21 | grep -i claude.md验证加载或直接询问 Claude 项目规范最佳实践建议在 CLAUDE.md 中放行为规范代码风格、禁止操作在 settings.json 中放技术配置allowedTools、blockedCommands两者配合使用故障排查流程图flowchart TD A[CLAUDE.md 未加载] -- B[检查文件位置] B -- C{.claude/CLAUDE.md 存在?} C --|否| D[创建 .claude/CLAUDE.md] C --|是| E[检查文件名大小写] D -- F[写入项目规范] E -- G{文件名全大写?} G --|否| H[重命名为 CLAUDE.md] G --|是| I[检查编码] H -- I F -- i[验证加载] I -- J{UTF-8 编码?} J --|否| K[iconv 转 UTF-8] J --|是| L[检查内容长度] K -- L L -- M{ 1000 字?} M --|否| N[精简内容] M --|是| O[claude --debug 验证] N -- O O -- P{已加载?} P --|是| Q[✅ 问题解决] P --|否| R[/clear 后重启] R -- S[询问 Claude 规范内容] S -- T{知道规范?} T --|是| Q T --|否| U[检查项目级 vs 用户级冲突] U -- V[合并或调整优先级] V -- Q