DeepDojo.AI发布 2026-11-12English

团队规则和个人偏好该放进哪个 CLAUDE.md

Claude CodeAI 编程

一个 monorepo 里有 frontend/ 和 backend/ 两个项目，各自放了一份 CLAUDE.md。你在 frontend/ 里启动 Claude Code，顺手让它改了一个后端接口，backend/CLAUDE.md 里那条“改接口要同步更新 OpenAPI 文件”却没有生效。

同一周，有人把自己本机的测试地址写进了根目录的 CLAUDE.md，提交后全组都读到了。

这两件事都和规则写得好不好无关，问题出在位置。CLAUDE.md 可以放在好几个地方，每个位置决定两件事：

  • 谁能看到它：只有你自己、整个团队，还是你本机的这个仓库；
  • 什么时候加载：启动时就读，还是等 Claude 碰到某个目录才读。

难点在于这两件事由不同的东西决定。存放位置决定共享范围，启动目录和访问范围决定本次加载。只看文件放在哪，很容易以为“提交到仓库的说明，每次都会被读到”。

处理办法是先按“谁该看到”选文件，再按启动目录推算这次会读到哪些；根文件越写越长时，把只对部分代码有效的规则挪进子目录或路径规则，让它们在需要时才加载。

01 四个位置，按谁该看到来选

日常项目最常使用四个位置：

位置影响范围典型内容是否共享
~/.claude/CLAUDE.md你的所有项目个人长期偏好、通用工具习惯通常不共享
项目根目录/CLAUDE.md整个仓库架构、命令、团队规范提交到 Git
项目根目录/.claude/CLAUDE.md整个仓库与根目录文件相同，便于集中管理 Claude 配置提交到 Git
项目根目录/CLAUDE.local.md当前仓库中的你本机地址、个人测试数据、临时偏好加入 .gitignore

根目录和 .claude/ 都能承载项目级指令。团队应选择一个主要位置，避免同类规则分散在多处。开头那个本机测试地址，应该放进 CLAUDE.local.md，并把它加进 .gitignore。

这张表和 Claude Code 的记忆文档一致：项目指令可以放在 ./CLAUDE.md 或 ./.claude/CLAUDE.md，个人的项目偏好放在 ./CLAUDE.local.md，它和 CLAUDE.md 一起加载、同等对待。

02 启动目录决定这次读到哪些

Claude Code 启动时，会从当前目录向上找指令文件，可能同时读到多份。官方文档的说法是：这些文件会拼接进上下文，彼此并不覆盖；顺序从文件系统根目录一直到你的工作目录，所以离启动位置越近的文件越晚被读到。同一层里，CLAUDE.local.md 排在 CLAUDE.md 之后。

较近目录的内容出现得更晚，也不能保证覆盖前面的文字要求。两条要求冲突，就回到原文件把冲突改掉。

monorepo 就是一个仓库里放多个项目。子目录说明会按访问范围加载，例如：

shop-platform/
├── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
└── backend/
    └── CLAUDE.md

从 frontend/ 启动，会加载根目录和 frontend/ 的说明，旁边的 backend/CLAUDE.md 不会一起加载。若从根目录启动，先读根目录规则；读到某个子目录的文件时，再按需加载那里的说明。官方文档写得更具体：工作目录下面的子目录里的 CLAUDE.md，要等 Claude 读取、写入或编辑那个子目录里的其他文件时才加载。

回到开头的例子：backend/ 不在 frontend/ 下面，从 frontend/ 启动就读不到它。需要同时改前后端时，从根目录启动更稳妥。

存放位置决定共享范围，启动目录和访问范围决定本次加载。把子目录说明提交到仓库，并不意味着所有兄弟目录的说明会同时进入上下文。想确认这次到底加载了哪几份，可以按CLAUDE.md 规则不被遵守的排查步骤，先用 /context 核对。

03 文件变长时，把规则挪到该在的位置

文件越写越长时，先看看里面是否混进低频内容。官方建议单个 CLAUDE.md 控制在 200 行以内，超过并不会立即失效，这个数字更像复查提醒。记忆文档给出的理由是：文件越长，占用的上下文越多，遵循程度也会下降。

用 @ 导入长文档可以改善文件组织，但导入的内容仍会加载，不能因此减少上下文占用。例如：

# 补充规则

- Git 流程见 @docs/git-workflow.md
- 发布约束见 @docs/release-rules.md

文件变长时，依次处理：

  1. 删除可从代码、配置和锁文件直接发现的信息；
  2. 把子项目专属规则移动到对应目录；
  3. 把只在特定文件上生效的要求写成路径规则；
  4. 把只在特定任务中使用的长方法移入 Skill。

第一步删什么，取决于哪些内容值得常驻，判断方法见CLAUDE.md 怎么写，Claude 才会照做。

04 用路径规则只在需要时加载

例如，把下面内容保存为 .claude/rules/api.md，就能为 API 文件单独提供要求。开头两个 --- 之间是 YAML 元数据，paths 指定匹配范围：

---
paths:
  - "src/api/**/*.ts"
---

# API 规则

- 所有写操作先调用 `requirePermission()`。
- 对外错误响应不得包含数据库异常或堆栈信息。

这类规则只在处理匹配文件时加载，比把前端、后端、数据库和发布细节全部塞进根目录更容易维护。要注意的是，.claude/rules/ 里没有写 paths 的规则文件，会在启动时和 .claude/CLAUDE.md 一样加载；想让它按需出现，就得写上匹配范围。

Claude Code 最佳实践也建议，只和某一部分代码有关的规则，应该限定在那部分代码上，别让它在每个任务里都占着位置。

放规则时，把两个问题分开想：放在哪个文件，决定谁能看到它；从哪个目录启动、碰到了哪些文件，决定这一次读到了什么。两个问题都想清楚，开头那条后端规则和那个本机地址，就各自有了该去的地方。