上了电子实验记录本，之前的实验记录怎么办
2026/7/9 4:15:20
【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-8
- CLAUDE.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 2>&1 | 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 # 步骤 3：Claude 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 2>&1 | 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 # 步骤 2：CLAUDE.md 放行为规范 # settings.json 放技术配置 # 步骤 3：两者配合使用4. 各方案对比总结
| 方案 | 适用场景 | 推荐指数 | 难度 |
|---|---|---|---|
| 方案一：正确位置 | 通用方案 | ⭐⭐⭐⭐⭐ | 低 |
| 方案二：文件名 | 拼写问题 | ⭐⭐⭐⭐⭐ | 低 |
| 方案三：编码修复 | 非 UTF-8 | ⭐⭐⭐⭐ | 低 |
| 方案四：控制长度 | 内容过长 | ⭐⭐⭐⭐⭐ | 低 |
| 方案五：/clear 后 | 上下文清空 | ⭐⭐⭐⭐ | 低 |
| 方案六：settings.json | 技术配置 | ⭐⭐⭐⭐ | 低 |
5. 常见问题 FAQ
5.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 2>&1 | 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 2>&1 | 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