Claude Code 的配置体系中claude.md的优先级和合并策略

在 Claude Code 中用户级别和项目级别的CLAUDE.md文件会同时起作用且项目级别的优先级更高。Claude Code 会将这两个文件的内容合并后加载。️ 完整的优先级金字塔简单来说Claude Code 的配置遵循“从泛化到具体”的原则越具体、越靠近当前任务的配置优先级越高。在用户级别~/.claude/CLAUDE.md和项目级别./CLAUDE.md之上还存在其他层级。从低到高的完整优先级排序如下用户级(~/.claude/CLAUDE.md): 优先级最低定义适用于你所有项目的个人偏好比如回复语言、代码注释风格等。项目级(./CLAUDE.md): 优先级中等定义当前项目的团队共享规范比如技术栈、构建命令、API约定等。本地项目级(./CLAUDE.local.md): 优先级较高用于存放你个人在特定项目中的私有配置这些配置不会提交到版本库。子目录级(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]。 配置核对清单配置文件主要用途是否提交 Git冲突优先级~/.claude/CLAUDE.md个人全局偏好语言、通用习惯否低./CLAUDE.md项目团队核心规范技术栈、命令、架构是中./CLAUDE.local.md个人项目偏好私有否高src/CLAUDE.md特定子目录的精确指令视情况最高