【Bug已解决】CLAUDE.md not loading / Custom instructions ignored — Claude Code 自定义指令未生效解决方案1. 问题描述在项目中配置了.claude/CLAUDE.md或~/.claude/CLAUDE.md自定义指令文件后Claude Code 完全忽略这些指令行为与未配置一样# 配置了 CLAUDE.md 但 Claude Code 不遵循 $ cat .claude/CLAUDE.md # 项目规范 - 使用 pnpm 而非 npm - 代码风格遵循 ESLint 配置 - 提交前运行 pnpm test $ claude 安装新依赖 # Claude Code 使用了 npm install 而非 pnpm add # 说明 CLAUDE.md 未被加载这个问题在以下场景中特别常见CLAUDE.md 文件路径错误CLAUDE.md 在项目子目录而非根目录使用了错误的文件名如 CLAUDE.txt、claude.md文件编码问题非 UTF-8Claude Code 版本不支持 CLAUDE.md项目级和用户级配置冲突2. 原因分析核心原理拆解Claude Code 启动 → 查找 CLAUDE.md 文件 ↓ 文件路径不对 / 文件名错误 / 编码问题 ↓ CLAUDE.md 未被加载到系统提示中 ↓ Claude Code 不知道自定义指令 ↓ 行为与默认一致原因分类表原因分类具体表现占比文件路径错误不在 .claude/ 目录或项目根目录约 35%文件名错误大小写错误或扩展名不对约 25%版本不支持Claude Code 版本太旧约 15%编码问题非 UTF-8 编码约 10%配置冲突项目级被用户级覆盖约 10%格式问题Markdown 格式导致解析失败约 5%3. 解决方案方案一确认正确的文件路径最推荐# Claude Code 查找 CLAUDE.md 的位置: # 1. 项目级: 项目根目录/.claude/CLAUDE.md # 2. 项目根级: 项目根目录/CLAUDE.md # 3. 用户级: ~/.claude/CLAUDE.md # 步骤 1确认文件位置 ls -la .claude/CLAUDE.md # 或 ls -la CLAUDE.md # 步骤 2确保在项目根目录 pwd # 应该是项目根目录 # 步骤 3创建正确的文件 mkdir -p .claude cat .claude/CLAUDE.md EOF # 项目规范 - 使用 pnpm 作为包管理器 - 代码风格遵循 ESLint 配置 - 提交前运行 pnpm test - commit message 使用 conventional commits 格式 EOF方案二验证文件名和大小写# 步骤 1确认文件名正确 # 正确: CLAUDE.md全大写 # 错误: claude.md, Claude.md, CLAUDE.MD, CLAUDE.txt ls -la .claude/CLAUDE.md # 确认文件名是 CLAUDE.md全大写 # 步骤 2macOS 不区分大小写Linux 区分 # 在 Linux 上确保使用正确的大小写方案三验证 Claude Code 版本# 步骤 1检查版本 claude --version # CLAUDE.md 支持需要较新版本 # 步骤 2如果版本太旧更新 npm update -g anthropic-ai/claude-code # 步骤 3重启 claude方案四检查文件编码# 步骤 1检查文件编码 file .claude/CLAUDE.md # 应该输出: ASCII text 或 UTF-8 Unicode 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方案五使用 /context 验证加载状态# 步骤 1在 Claude Code 中执行 /context # 查看系统提示中是否包含 CLAUDE.md 内容 # 步骤 2如果看不到 CLAUDE.md 内容 # 说明文件未被加载 # 步骤 3使用 --debug 查看加载日志 claude --debug # 查看是否有 Loading CLAUDE.md 相关日志方案六避免配置冲突# 步骤 1检查是否有多个 CLAUDE.md find ~ -name CLAUDE.md 2/dev/null find . -name CLAUDE.md 2/dev/null # 步骤 2用户级 CLAUDE.md 和项目级 CLAUDE.md 会合并 # 项目级优先 # 如果用户级有冲突指令删除或修改 # 步骤 3确保只有必要的 CLAUDE.md # 用户级: ~/.claude/CLAUDE.md (通用偏好) # 项目级: .claude/CLAUDE.md (项目特定规范)4. 各方案对比总结方案适用场景推荐指数难度方案一确认路径路径错误⭐⭐⭐⭐⭐低方案二验证文件名文件名错误⭐⭐⭐⭐⭐低方案三更新版本版本太旧⭐⭐⭐⭐低方案四检查编码编码问题⭐⭐⭐低方案五/context 验证确认加载⭐⭐⭐⭐⭐低方案六避免冲突多文件冲突⭐⭐⭐⭐低5. 常见问题 FAQ5.1 CLAUDE.md 支持哪些位置.claude/CLAUDE.md项目级配置推荐CLAUDE.md项目根目录也支持~/.claude/CLAUDE.md用户级配置全局三者会合并使用项目级优先于用户级。5.2 CLAUDE.md 中应该写什么项目工具链说明包管理器、lint、测试命令代码风格和规范Git 提交规范项目架构说明不应修改的文件/目录5.3 CLAUDE.md 的大小限制没有严格限制但建议控制在 2000 字以内。过长的 CLAUDE.md 会占用上下文空间。5.4 修改 CLAUDE.md 后需要重启吗不需要。Claude Code 会在新会话中自动加载最新的 CLAUDE.md。但当前会话不会重新加载。5.5 子目录中的 CLAUDE.md 会加载吗不会。Claude Code 只加载项目根目录和.claude/目录下的 CLAUDE.md。子目录中的不会加载。5.6 如何确认 CLAUDE.md 已被加载使用/context命令查看系统提示内容或使用--debug模式查看加载日志。5.7 用户级和项目级 CLAUDE.md 冲突怎么办项目级优先。如果用户级有通用偏好如使用中文回复项目级有特定规范如使用英文注释两者会合并项目级的特定指令覆盖用户级的通用指令。5.8 CLAUDE.md 中可以使用变量或模板吗不支持。CLAUDE.md 是纯 Markdown 文件不支持变量替换或模板语法。5.9 多个项目共享 CLAUDE.md将通用的 CLAUDE.md 放在~/.claude/CLAUDE.md中作为用户级配置所有项目共享。项目特定的规范放在项目级.claude/CLAUDE.md中。5.10 排查清单速查表□ 1. 确认文件路径: .claude/CLAUDE.md 或项目根目录/CLAUDE.md □ 2. 确认文件名: CLAUDE.md全大写 □ 3. 检查文件编码: file .claude/CLAUDE.mdUTF-8 □ 4. 使用 /context 验证是否加载 □ 5. 更新 Claude Code 到最新版本 □ 6. 检查是否有多个 CLAUDE.md 冲突 □ 7. 使用 --debug 查看加载日志 □ 8. 确保在项目根目录启动 claude □ 9. 控制文件大小在 2000 字以内 □ 10. 修改后开新会话测试6. 总结根本原因CLAUDE.md 未生效最常见原因是文件路径错误35%和文件名大小写错误25%最佳实践将项目规范放在.claude/CLAUDE.md中全大写文件名使用/context验证是否被加载文件位置项目级.claude/CLAUDE.md和用户级~/.claude/CLAUDE.md会合并使用项目级优先内容建议在 CLAUDE.md 中声明项目工具链包管理器、lint、测试命令和 Git 提交规范这是最高价值的内容最佳实践建议将通用偏好放在用户级~/.claude/CLAUDE.md项目特定规范放在项目级.claude/CLAUDE.md实现分层配置故障排查流程图flowchart TD A[CLAUDE.md 未生效] -- B[确认文件路径] B -- C{文件存在于正确位置?} C --|否| D[创建 .claude/CLAUDE.md] C --|是| E[验证文件名大小写] D -- F[重启 Claude Code] E -- G{文件名正确?} G --|否| H[重命名为 CLAUDE.md] G --|是| I[检查文件编码] H -- F I -- J{编码为 UTF-8?} J --|否| K[转换为 UTF-8] J --|是| L[使用 /context 验证加载] K -- F L -- M{CLAUDE.md 内容在上下文中?} M --|是| N[✅ 问题解决] M --|否| O[检查 Claude Code 版本] O -- P{版本是否最新?} P --|否| Q[更新版本] P --|是| R[使用 --debug 查看日志] Q -- F R -- S[根据日志修复] S -- N
【Bug已解决】CLAUDE.md not loading / Custom instructions ignored — Claude Code 自定义指令未生效解决方案
发布时间：2026/7/8 8:17:09
【Bug已解决】CLAUDE.md not loading / Custom instructions ignored — Claude Code 自定义指令未生效解决方案1. 问题描述在项目中配置了.claude/CLAUDE.md或~/.claude/CLAUDE.md自定义指令文件后Claude Code 完全忽略这些指令行为与未配置一样# 配置了 CLAUDE.md 但 Claude Code 不遵循 $ cat .claude/CLAUDE.md # 项目规范 - 使用 pnpm 而非 npm - 代码风格遵循 ESLint 配置 - 提交前运行 pnpm test $ claude 安装新依赖 # Claude Code 使用了 npm install 而非 pnpm add # 说明 CLAUDE.md 未被加载这个问题在以下场景中特别常见CLAUDE.md 文件路径错误CLAUDE.md 在项目子目录而非根目录使用了错误的文件名如 CLAUDE.txt、claude.md文件编码问题非 UTF-8Claude Code 版本不支持 CLAUDE.md项目级和用户级配置冲突2. 原因分析核心原理拆解Claude Code 启动 → 查找 CLAUDE.md 文件 ↓ 文件路径不对 / 文件名错误 / 编码问题 ↓ CLAUDE.md 未被加载到系统提示中 ↓ Claude Code 不知道自定义指令 ↓ 行为与默认一致原因分类表原因分类具体表现占比文件路径错误不在 .claude/ 目录或项目根目录约 35%文件名错误大小写错误或扩展名不对约 25%版本不支持Claude Code 版本太旧约 15%编码问题非 UTF-8 编码约 10%配置冲突项目级被用户级覆盖约 10%格式问题Markdown 格式导致解析失败约 5%3. 解决方案方案一确认正确的文件路径最推荐# Claude Code 查找 CLAUDE.md 的位置: # 1. 项目级: 项目根目录/.claude/CLAUDE.md # 2. 项目根级: 项目根目录/CLAUDE.md # 3. 用户级: ~/.claude/CLAUDE.md # 步骤 1确认文件位置 ls -la .claude/CLAUDE.md # 或 ls -la CLAUDE.md # 步骤 2确保在项目根目录 pwd # 应该是项目根目录 # 步骤 3创建正确的文件 mkdir -p .claude cat .claude/CLAUDE.md EOF # 项目规范 - 使用 pnpm 作为包管理器 - 代码风格遵循 ESLint 配置 - 提交前运行 pnpm test - commit message 使用 conventional commits 格式 EOF方案二验证文件名和大小写# 步骤 1确认文件名正确 # 正确: CLAUDE.md全大写 # 错误: claude.md, Claude.md, CLAUDE.MD, CLAUDE.txt ls -la .claude/CLAUDE.md # 确认文件名是 CLAUDE.md全大写 # 步骤 2macOS 不区分大小写Linux 区分 # 在 Linux 上确保使用正确的大小写方案三验证 Claude Code 版本# 步骤 1检查版本 claude --version # CLAUDE.md 支持需要较新版本 # 步骤 2如果版本太旧更新 npm update -g anthropic-ai/claude-code # 步骤 3重启 claude方案四检查文件编码# 步骤 1检查文件编码 file .claude/CLAUDE.md # 应该输出: ASCII text 或 UTF-8 Unicode 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方案五使用 /context 验证加载状态# 步骤 1在 Claude Code 中执行 /context # 查看系统提示中是否包含 CLAUDE.md 内容 # 步骤 2如果看不到 CLAUDE.md 内容 # 说明文件未被加载 # 步骤 3使用 --debug 查看加载日志 claude --debug # 查看是否有 Loading CLAUDE.md 相关日志方案六避免配置冲突# 步骤 1检查是否有多个 CLAUDE.md find ~ -name CLAUDE.md 2/dev/null find . -name CLAUDE.md 2/dev/null # 步骤 2用户级 CLAUDE.md 和项目级 CLAUDE.md 会合并 # 项目级优先 # 如果用户级有冲突指令删除或修改 # 步骤 3确保只有必要的 CLAUDE.md # 用户级: ~/.claude/CLAUDE.md (通用偏好) # 项目级: .claude/CLAUDE.md (项目特定规范)4. 各方案对比总结方案适用场景推荐指数难度方案一确认路径路径错误⭐⭐⭐⭐⭐低方案二验证文件名文件名错误⭐⭐⭐⭐⭐低方案三更新版本版本太旧⭐⭐⭐⭐低方案四检查编码编码问题⭐⭐⭐低方案五/context 验证确认加载⭐⭐⭐⭐⭐低方案六避免冲突多文件冲突⭐⭐⭐⭐低5. 常见问题 FAQ5.1 CLAUDE.md 支持哪些位置.claude/CLAUDE.md项目级配置推荐CLAUDE.md项目根目录也支持~/.claude/CLAUDE.md用户级配置全局三者会合并使用项目级优先于用户级。5.2 CLAUDE.md 中应该写什么项目工具链说明包管理器、lint、测试命令代码风格和规范Git 提交规范项目架构说明不应修改的文件/目录5.3 CLAUDE.md 的大小限制没有严格限制但建议控制在 2000 字以内。过长的 CLAUDE.md 会占用上下文空间。5.4 修改 CLAUDE.md 后需要重启吗不需要。Claude Code 会在新会话中自动加载最新的 CLAUDE.md。但当前会话不会重新加载。5.5 子目录中的 CLAUDE.md 会加载吗不会。Claude Code 只加载项目根目录和.claude/目录下的 CLAUDE.md。子目录中的不会加载。5.6 如何确认 CLAUDE.md 已被加载使用/context命令查看系统提示内容或使用--debug模式查看加载日志。5.7 用户级和项目级 CLAUDE.md 冲突怎么办项目级优先。如果用户级有通用偏好如使用中文回复项目级有特定规范如使用英文注释两者会合并项目级的特定指令覆盖用户级的通用指令。5.8 CLAUDE.md 中可以使用变量或模板吗不支持。CLAUDE.md 是纯 Markdown 文件不支持变量替换或模板语法。5.9 多个项目共享 CLAUDE.md将通用的 CLAUDE.md 放在~/.claude/CLAUDE.md中作为用户级配置所有项目共享。项目特定的规范放在项目级.claude/CLAUDE.md中。5.10 排查清单速查表□ 1. 确认文件路径: .claude/CLAUDE.md 或项目根目录/CLAUDE.md □ 2. 确认文件名: CLAUDE.md全大写 □ 3. 检查文件编码: file .claude/CLAUDE.mdUTF-8 □ 4. 使用 /context 验证是否加载 □ 5. 更新 Claude Code 到最新版本 □ 6. 检查是否有多个 CLAUDE.md 冲突 □ 7. 使用 --debug 查看加载日志 □ 8. 确保在项目根目录启动 claude □ 9. 控制文件大小在 2000 字以内 □ 10. 修改后开新会话测试6. 总结根本原因CLAUDE.md 未生效最常见原因是文件路径错误35%和文件名大小写错误25%最佳实践将项目规范放在.claude/CLAUDE.md中全大写文件名使用/context验证是否被加载文件位置项目级.claude/CLAUDE.md和用户级~/.claude/CLAUDE.md会合并使用项目级优先内容建议在 CLAUDE.md 中声明项目工具链包管理器、lint、测试命令和 Git 提交规范这是最高价值的内容最佳实践建议将通用偏好放在用户级~/.claude/CLAUDE.md项目特定规范放在项目级.claude/CLAUDE.md实现分层配置故障排查流程图flowchart TD A[CLAUDE.md 未生效] -- B[确认文件路径] B -- C{文件存在于正确位置?} C --|否| D[创建 .claude/CLAUDE.md] C --|是| E[验证文件名大小写] D -- F[重启 Claude Code] E -- G{文件名正确?} G --|否| H[重命名为 CLAUDE.md] G --|是| I[检查文件编码] H -- F I -- J{编码为 UTF-8?} J --|否| K[转换为 UTF-8] J --|是| L[使用 /context 验证加载] K -- F L -- M{CLAUDE.md 内容在上下文中?} M --|是| N[✅ 问题解决] M --|否| O[检查 Claude Code 版本] O -- P{版本是否最新?} P --|否| Q[更新版本] P --|是| R[使用 --debug 查看日志] Q -- F R -- S[根据日志修复] S -- N
