在 Claude Code 中，用户级别和项目级别的 CLAUDE.md 文件会同时起作用，且项目级别的优先级更高。Claude Code 会将这两个文件的内容合并后加载。

🏗️ 完整的优先级金字塔

简单来说，Claude Code 的配置遵循“从泛化到具体”的原则，越具体、越靠近当前任务的配置，优先级越高。

在用户级别（~/.claude/CLAUDE.md）和项目级别（./CLAUDE.md）之上，还存在其他层级。从低到高的完整优先级排序如下：

1. 用户级 (~/.claude/CLAUDE.md): 优先级最低，定义适用于你所有项目的个人偏好，比如回复语言、代码注释风格等。
2. 项目级 (./CLAUDE.md): 优先级中等，定义当前项目的团队共享规范，比如技术栈、构建命令、API约定等。
3. 本地项目级 (./CLAUDE.local.md): 优先级较高，用于存放你个人在特定项目中的私有配置，这些配置不会提交到版本库。
4. 子目录级 (src/CLAUDE.md): 优先级最高，仅在 Claude 操作该目录下的文件时加载，提供最精确的上下文指令。

在这些用户自定义的层级之上，还存在企业/组织级配置（如 /etc/claude-code/CLAUDE.md），其优先级最高且为只读，用于强制执行公司的统一规则。

⚖️ 冲突处理：“合并”而非“覆盖”

你可能听说过“覆盖”这个词，但这其实不太准确。Claude Code 真正的处理方式是 “合并”，而非传统意义上的覆盖。

• 合并机制：在会话启动时，Claude Code 会从用户级别开始，依次向上加载所有找到的 CLAUDE.md 文件，并将它们的内容全部拼接（Merge）在一起，最终形成一条完整的系统指令[reference:12]。
• 规则冲突：当不同级别的文件包含冲突的指令时，优先级高的文件会“胜出”，影响模型的行为。例如，如果项目级规定“使用 pnpm 作为包管理器”，但你的用户级规定“使用 npm”，那么项目级的规则优先级更高，Claude 会遵循 pnpm。

理解这一“合并”而非“覆盖”的逻辑，能帮助你更好地规划各层级 CLAUDE.md 的内容，避免规则冲突导致的混乱。

💡 最佳实践建议

根据上述规则，一个清晰的分层配置策略能让你和团队的协作更高效：

• 用户级 (~/.claude/CLAUDE.md)：存放你个人的通用偏好，例如“使用中文回答”、“代码注释用英文”、“提交信息遵循 Conventional Commits 规范”等[reference:16][reference:17]。
• 项目级 (./CLAUDE.md)：存放整个项目团队共享的、必须遵守的核心规范。例如，项目的技术栈、代码风格、测试框架、构建与部署命令等[reference:18][reference:19]。
• 本地项目级 (./CLAUDE.local.md)：存放你个人在当前项目中的偏好，比如“解释代码时优先给出测试文件路径”、“回答时提供更详细的步骤”等[reference:20][reference:21]。
• 子目录级 (src/CLAUDE.md)：用于在大型项目（如 Monorepo）中，为特定子模块（如 src/api、tests/）提供专属规则，避免项目根目录的 CLAUDE.md 过于臃肿[reference:22][reference:23]。

📋 配置核对清单