Claude Code 从 CLAUDE.md 文件加载指令。放在哪里决定了谁能拿到、什么时候拿到。层级搞错了，要么行为不一致，要么每次编辑都淹没在无关规则里。
三个层级
用户级：~/.claude/CLAUDE.md
在某一个开发者的机器上。不版本控制。不共享。把它当个人偏好——缩进大小、输出详细度、快捷方式。别人看不到。
项目级：.claude/CLAUDE.md
在仓库根目录。版本控制。每个克隆仓库的开发者自动获得。团队编码标准该放这里——命名规范、测试要求、提交消息格式。一个文件，提交一次，下次 pull 全员生效。
目录级：子目录中的 CLAUDE.md
在特定目录内。只在 Claude Code 编辑该目录或其子目录中的文件时加载。database/CLAUDE.md 中的数据库迁移规则在你动迁移时加载，不在你编辑 React 组件时加载。
所有生效层级同时加载。编辑 src/api/handler.py 时，Claude Code 看到用户级 + 项目级 + src/api/CLAUDE.md（如果存在）。它们叠加——不是互相替换。
经典错误：团队标准放在用户级
这是最常见的反模式。一个高级开发者在 ~/.claude/CLAUDE.md 里设好编码标准。在他机器上一切正常。新人克隆仓库——没有标准。Claude Code 无视团队约定的每一条规范。
根因一旦看到就很明显：~/.claude/ 是 home 目录。克隆 git 仓库不会复制别人的 home 目录。如果 8 个开发者中只有 5 个手动配了用户级标准，40% 的 Claude Code 建议会违反团队规范。修复就是一行：移到项目根目录的 .claude/CLAUDE.md。
用户级配置是给真正个人化的东西——你偏好的解释详细程度、编辑器习惯、语言偏好。团队必须遵循的东西不该放这里。
第二个错误：所有东西一个文件
同事说：“咱们简单点。一个根级 CLAUDE.md，所有规则放一处。”
问题是：单个根级文件在每次文件编辑时都加载。你的 React 组件规则在编辑 Python 后端代码时加载。你的数据库迁移规则在编辑前端测试时加载。这浪费上下文 token，还可能产出无关建议——25% 的建议可能引用了完全错误的框架。
团队规模不是决定因素。一个有 React、Python 和 SQL 的 5 人项目从范围划定中获益和 50 人项目一样多。标准是文件类型多样性，不是人数。
实践中的正确范围
标准项目： 三种配置 → 三个层级。
| 什么 | 放哪里 | 为什么 |
|---|---|---|
| 个人偏好（缩进、详细度） | ~/.claude/CLAUDE.md | 个人的，不共享 |
| 团队标准（命名、测试） | .claude/CLAUDE.md | 共享，版本控制 |
| 区域专属规则（DB 迁移） | database/CLAUDE.md | 只在相关时加载 |
多服务 monorepo： 根级放通用标准（共享库规范）。服务级放服务专属规则。
monorepo/
├── .claude/CLAUDE.md ← 通用共享库标准
├── api/CLAUDE.md ← Python API 规则
├── web/CLAUDE.md ← React 前端规则
└── mobile/CLAUDE.md ← 移动应用规则编辑共享库代码时，只加载通用规则。编辑 api/ 代码时，通用和 API 专属规则都加载。Claude Code 不会在一个文件内选择性应用”章节”——把文件放在合适的层级来实现范围划定。
.claude/rules/ — 模块化替代方案
不用一个巨大的 .claude/CLAUDE.md，你可以把项目级规则拆成 .claude/rules/ 下的主题文件。每个文件可以用 YAML frontmatter 的 paths glob 控制何时加载。
这解决了项目级的范围问题。一个 paths: ["tests/**"] 的规则文件只在编辑测试文件时加载。一个 paths: ["src/api/**"] 的规则文件只在编辑后端代码时加载。没有 paths 的规则文件对所有文件加载——和根 CLAUDE.md 一样。
没有 paths 配置的规则文件对所有东西加载。如果把 React、Python 和数据库规则都放在 .claude/rules/ 但不加 paths，你会得到和单个根 CLAUDE.md 一样的”所有东西到处加载”问题。
审计数据：范围不当的实际代价
一个团队审计发现三个不同问题，每个都由范围不匹配导致：
- 40% 的建议违反标准 — 标准在用户级配置里。8 个开发者中只有 5 个有。修复：移到项目级。
- 25% 的建议引用了错误框架 — React 规则在根级，编辑 Python 文件时也加载。修复：目录级或 paths 范围的规则。
- 15% 的测试建议忽略约定 — 测试规则没有范围到测试文件。修复：
.claude/rules/加paths: ["tests/**"]。
三个都通过把每条规则放到正确范围来修复。
另外，将 MCP 工具配置（.mcp.json）和 CLAUDE.md 使用指南结合，把工具选择准确率从 65%（只有工具）推到了 91%（工具 + 指南）。CLAUDE.md 不替代工具描述——它用描述本身无法提供的上下文指导来补充它们。
不存在的东西
- CLAUDE.md 中的条件注释 — 你不能在一个文件里写”如果编辑 Python，应用这些规则”。范围来自文件放置和 paths glob，不是内联条件。
- CLAUDE.md 中的 MCP server 配置 —
.mcp.json是 MCP server 的专用机制。CLAUDE.md 是给指令的。它们服务不同目的和不同格式。 - 子目录
.mcp.json— MCP 配置在项目根目录。目录范围的 MCP server 不存在。
一句话总结： 用户级是个人的，项目级是团队的，目录级是上下文的——把每条规则放到它实际需要在的位置，别再让数据库规则在 React 编辑时加载了。