1. 膨胀的 CLAUDE.md：问题到底出在哪一块
我用 Claude Code 的时间不算短，刚开始接触时觉得 CLAUDE.md 这机制简直是救星：把项目约定写成一份说明文档，AI 就能照着做。于是习惯性往里堆东西——编码风格、禁止事项、数据库迁移规范、组件命名规则、提交信息格式、发布流程、依赖版本……半年之后，根目录那个 CLAUDE.md 从 6 行膨胀到了 600 多行。
膨胀带来的后果很直观。最明显的信号是 Claude 开始“选择性失明”：明明我在文件前半部分写了“数据库迁移必须带 down 回滚”，当它去 backend 目录处理任务时，依然会建议我跑一条没有 down 的修改语句；明明写了“提交信息要遵循 Conventional Commits”，结果一次 commit 它还是用了自由文本。我一度以为是模型能力不行，后来才意识到，问题是规则文件太长，长到重点指令的权重被稀释了。
CLAUDE.md 的核心价值不是“让 AI 看到所有规则”，而是“让 AI 在正确的时候看到正确的规则”。把所有规则压在一个全局文件里，等于让每次对话都背着整个项目的背景设定在跑。既浪费 token，又掩盖了真正的高优先级约束。这篇文章不聊虚的，直接给一套我验证过的切割方案：什么样的规则必须留在顶层，什么样的规则该下沉到子目录，拆完之后怎么确认 Claude 真的按新结构执行。
2. 规则加载模型：Claude Code 到底怎么读 CLAUDE.md
2.1 三层规则构成：用户级、根目录、子目录
Claude Code 的规则加载不是“只认一个文件”，而是分层的。官方文档里的模型大致是这样：启动时会先读用户级的~/.claude/CLAUDE.md，这层管的是你个人跨项目的通用偏好，比如你习惯用哪些编辑器、commit message 偏好什么风格、常用哪些命令组合。
然后是项目根目录的CLAUDE.md，这层管的是整个仓库的“公共宪法”。最后，当 Claude 进入项目的某个子目录去处理具体任务时，它会继续加载该子目录下的CLAUDE.md，这层管的是局部细节。
这三层不是互相替换，而是叠加的。用户级先给底子，根目录往上加，子目录再在局部场景里做补充。我一开始犯的错就是忽略了第三层，把所有东西都塞进根目录，结果就是局部规则污染了全局执行。
2.2 子目录规则是在什么时机触发的
很多人理解子目录 CLAUDE.md 时有一个误区，以为只要文件放在那里 Claude 就会第一时间读。实际上它的触发逻辑更接近“按需”。当 Claude 正在处理根目录任务时，它不会把每个子目录的 CLAUDE.md 都扫一遍；只有当任务真正涉及到该目录下的文件、命令或上下文时，对应子目录的规则才会被拉进来。
这个特性其实非常有用。它意味着你可以在子目录里写非常具体的规则，而这些规则不会干扰全局任务。比如我在backend/CLAUDE.md里写“所有数据库迁移必须显式提供 down Revision”，这条规则只在涉及 backend 开发时生效，处理前端任务时根本不会占用任何上下文空间。
理解了触发时机，你就掌握了分流的核心判断标准：这条规则是否需要在每一次对话里出现？如果不是，就让它下沉到子目录，需要时才加载。
2.3 不拆分的隐性成本：注意力稀释与上下文碎片化
CLAUDE.md 太长还有一个容易被忽略的成本：注意力稀释。模型在长文本里提取关键指令的能力并不是线性的，文件越长，越靠后的内容被严格遵守的概率越低。我做过一个很简单的实验：把一个 10 行的规则文件和一个 400 行的规则文件放在两个项目里，同样下达“写一个计算器函数”，后者对你的风格约束的遵守程度明显弱于前者。这跟模型能力没关系，是人脑都会犯的毛病——写满 10 条注意事项的说明书，你大概率只记得住前三条。
另外每一次对话开始时，系统自动读取这一整套记忆文件的内容进入上下文窗口。文件膨胀意味着每次交互的固定消耗都在涨。这不是一个可忽略的小数目，尤其是长时间多轮对话时，前期规则占用的上下文越多，留给真实代码和任务信息的空间就越少，模型的表现自然下降。
3. 留在顶层文件里的规则：全局级宪法的三块基石
3.1 项目身份与关键路径索引
顶层 CLAUDE.md 的第一项任务不是写规则，而是让 Claude 知道“这是什么项目、在哪里找到什么东西”。我会在开头写清楚项目定位、整体技术栈、目录结构概览、构建与测试入口。这一段的作用是把 AI 快速拉进项目语境，它不需要很详细，但必须准确。
比如我会写：
- 项目类型：面向用户的 Web 应用，前端 React + TypeScript，后端 Python FastAPI
- 仓库根目录结构：
frontend/、backend/、docs/、scripts/ - 常用命令：
npm run dev启动前端，uvicorn app.main:app --reload启动后端 - 测试入口：前端
npm test，后端pytest backend/tests
这段信息适合放顶层，原因很简单：几乎任何一个任务都要先确认自己在哪个上下文里工作。如果这段信息放到子目录，Claude 每次都要先猜项目结构，容易产生路径幻觉。
3.2 零容忍的安全红线：必须全局生效
安全类规则必须放在顶层，这一类没有商量的余地。比如“不要执行数据库的 drop 操作”“不要向生产环境推送密钥或 .env 文件”“任何时候不得使用git push --force覆盖远程 main 分支”。这类规则的特点是后果严重，而且不管你在哪一个子目录工作都有触发的可能，所以它们必须对所有任务生效。
这里有一个实操细节值得多说两句。安全规则的写法要尽量“可判定”。与其写“注意安全，小心删除数据”，不如写“禁止执行以 DROP 开头的 SQL 语句，除非用户明确输入了 drop 关键词”。规则越明确，Claude 越容易在生成代码或执行命令之前进行自我拦截。安全规则不要用模糊的形容词，要用精确的动词和条件。
3.3 跨目录通用的工程规范
还有一些规则是无论处理哪个模块都应该遵守的，也该留在顶层，主要是编码风格和协作流程层面的东西。例如：
- 提交信息必须符合 Conventional Commits：
feat:、fix:、docs:等类型前缀 - 代码合并到主分支前必须通过全部测试和 lint 检查
- 新增功能必须附带单元测试，不提交无测试的代码
- 修改公共接口时必须同步更新对应文档
这类规则并不是某个目录的专属需求，而是整个项目协作的底线，所以放顶层。但我要提醒一句：顶层规则的质量比数量重要。理想状态下整个根目录文件保持在 80 到 120 行之间，如果你发现超过 200 行还没有触顶的迹象，差不多就该做“下沉手术”了。
4. 适合下沉到子目录的规则：按需加载的局部规章
4.1 技术栈专属规则，跟目录走
技术栈专属规则是最典型的“必须下沉”的东西。比如 backend 项目如果用了 FastAPI，你可以规定路由文件统一放app/routers/下、数据模型放app/models/、迁移脚本必须写 down 回滚、数据库连接信息从环境变量读取。再比如前端项目如果绑定了特定 UI 组件库，你可以规定不允许硬编码颜色值、必须使用设计系统里的 token、React 组件 props 必须定义 TypeScript interface。
这些规则放到根目录的问题很明显：处理前端任务时，后端数据库规范完全派不上用场，它只是占位符，白白消耗注意力。下沉到backend/CLAUDE.md和frontend/CLAUDE.md之后，Claude 只有在真正进入那个目录时才把这些技能树加载进来。这才是“按需加载”的正确用法。
我这里给一个简单的判断标准：如果你说“这条规则只对某个技术栈有意义”，那它就该待在那个技术栈对应的目录里。不要因为“万一哪天用得上”就留在顶层，顶层空间是留给高优先级通用规则的。
4.2 长文参考类内容：文档文件不是规则文件
CLAUDE.md 里不太适合放很长很长的参考内容，比如完整的数据库字段字典、几十个接口的请求响应示例、详细的项目架构说明。这些内容的特点是“很重要，但不是每次对话都需要”。如果全部硬塞进 CLAUDE.md，文件会迅速失控。
正确的做法是：长文参考类内容拆成独立文档，放在docs/目录下，然后在对应目录的 CLAUDE.md 里给出引用路径。比如我在backend/CLAUDE.md里不是粘贴整张数据库表清单，而是写一句“数据库表结构与字段含义见docs/database-schema.md，涉及数据库结构变更前先阅读该文档”。
Claude Code 支持这种文件间引用的用法，当任务涉及数据库变更时，它顺着路径去读详细文档，不会反过头来把几百行表格塞进每一次对话。这一招对控制顶层文件体量非常有效。
4.3 工具参数和版本敏感信息，放到离工具最近的目录
另一个值得下沉的类别是工具链相关的参数信息。比如“本地联调端口是 8000”“Redis 在 docker-compose 里启动，服务名是 redis-cache”“构建产物输出到 dist/assets”。这类信息跟具体目录强相关，很容易变化，而且不需要在所有任务里刷存在感。
版本敏感信息尤其要小心。比如前端项目某个时候锁定了 React 18，并且规定不要用默认导出；过半年升级到 React 19 之后，这个规则可能就变了。如果当初写在根目录，每次更新都要拖累整个项目的上下文；如果写在frontend/CLAUDE.md，维护成本会小得多，也更容易定位到相关改动位置。
5. 一次完整的“瘦身”实操：从 600 行拆到 80 行
5.1 第一步：建立规则清单，打上“是否全局”标签
拆分之前先把现有 CLAUDE.md 从头到尾读一遍，把每一条规则提炼成一个条目，写在临时文件或者表格里。我给每一条规则打三个标签：生效范围是全部任务还是局部任务？当前内容是否是可执行的规则还是参考资料？是否涉及安全风险？
拿我自己的项目举例，当时抽出来大概四十条。其中“提交信息用 Conventional Commits”“禁止强制推送 main”“新增代码必须有测试”这三条打了全局标签。剩下三十多条都跟具体技术栈绑定——FastAPI 的路由组织、React 组件的目录位置、docs 文件的 frontmatter、Docker 服务的启动参数——全部标成局部。
5.2 第二步：构建目标目录结构，选择下沉位置
根据项目实际结构，我建议你按第一层目录来分。常见的切法是：
backend/CLAUDE.md：后端框架、数据库、迁移、API 相关的规范frontend/CLAUDE.md：前端组件、样式、状态管理、构建工具相关的规范docs/CLAUDE.md：文档写作标准、目录结构、发布流程scripts/CLAUDE.md：脚本编写规范、命令行约定、CI 辅助工具deploy/CLAUDE.md：部署流程、环境配置、容器相关约束
这里的原则是粗粒度优先，不要一开始就按函数模块拆成十几个文件。子目录规则粒度太细反而会引入新的认知负担，Claude 每次要判断“当前任务属于哪一条”，反而容易漏读。
5.3 第三步：把参考类内容剥离为 doc 文件
抽完规则之后，你会发现还有一堆很长的参考内容既不属于单一目录，也不是规则。比如我当时有一份完整的接口返回格式约定，大概三百行，几乎没法塞进任何目录的 CLAUDE.md。这种内容的归宿是docs/下的独立文档。
留下一句引导性的引用就可以。效果类似这样：在backend/CLAUDE.md写上“所有 API 响应统一使用docs/api-response-style.md中规定的 envelope 格式，写接口前先阅读该文档”。让 Claude 按需去读。
5.4 第四步：重建顶层文件，只保留“最低限度的全局共识”
所有局部规则抽走之后，顶层 CLAUDE.md 重新整理。我的模板大致如下：
- 项目定位和仓库结构（10 行）
- 常用命令清单（10 行）
- 全局工程规范（提交信息、测试要求、代码审查流程，约 15 行）
- 零容忍安全红线（5 行）
- 子目录规则索引（5 行，简要列出每个子目录 CLAUDE.md 的覆盖范围）
拆分完成后根目录文件大概 80 行左右。这个体量对 Claude 来说非常友好，读一遍就能快速建立整体预期，而真正深入细节时又会自动加载子目录规则。
5.5 第五步：验证是否生效的实测方法
拆分之后不要直接开干，先做一轮验证。我会准备三个测试任务：
- 在根目录问一个项目结构的问题，确认 Claude 能正确描述顶层目录
- 在
backend/目录里让它创建一个数据库迁移文件，确认它应用了 backend 子目录规则 - 在
frontend/目录里让它创建组件，确认它遵守组件规范
如果哪一步失效，我通常会检查子目录文件名是否拼写正确、文件位置是否与项目结构对齐、顶层索引里是否写清了引用关系。大多数时候都是小问题，检查完就能恢复正常。
6. 拆分之后仍然会踩到的坑，以及排查技巧
6.1 子目录规则与顶层规则冲突时，听谁的？
子目录规则和顶层规则不是“覆盖”关系，而是“叠加”关系。如果两处对同一个行为给了不同指令，Claude 会倾向于采用更贴近当前场景的那份规则，也就是子目录规则。但这不代表顶层规则应该写一些与子目录冲突的内容——冲突本身就会带来混乱，Claude 在两者之间做选择时可能会产生随机性。
我的经验是：顶层规则写底线，子目录规则写做法。比如顶层写“所有新增功能必须附带测试”，这是底线；backend/CLAUDE.md里写“后端测试统一用 pytest，测试文件放对应模块的 tests 目录”，这是做法。两者不冲突，但一个管“要什么”，一个管“怎么做”。不要在一个层面把话说死，给子目录留出细化空间，是减少冲突的核心方法。
6.2 下沉之后反而失效，多半是引用路径写错了
我曾经把子目录规则拆好之后发现一个奇怪现象：在frontend/目录下工作时，React 组件规范完全没生效，Claude 依然自由发挥。查了半天，原因是顶层索引里写的路径是frontend/CLAUDE.md，但实际目录名是web/。这种路径错位在拆分初期非常常见。
排查方法很简单：在相关目录下发起一个新会话，直接问 Claude“你现在应该遵守哪些规则”，它会列出当前加载了哪些文件。对照一下就知道是不是路径写错、文件漏放、或者没有触发子目录加载条件。
6.3 子目录 CLAUDE.md 也会膨胀，还需要二次拆分
拆完根目录之后不要以为就一劳永逸了。我遇到过backend/CLAUDE.md因为内容增长而慢慢膨胀到两百多行的情况，因为后端涉及的领域确实多：ORM 规范、迁移规范、API 风格、数据库连接、测试策略、部署配置全都堆了过来。
这时候要做二次下沉。常见手法是在backend/下继续分，比如backend/app/CLAUDE.md放业务代码规范，backend/tests/CLAUDE.md放测试规范，backend/alembic/CLAUDE.md放迁移脚本规范。原则跟第一轮一样：规则是否只在这个更小的范围内生效？是就继续往深层沉。
6.4 不要为了“整齐”创建多余的空目录规则文件
还有一种过度设计的坑：为了让目录结构看起来完美，在根本没实际内容的目录里创建空 CLAUDE.md，只写几句“这个目录负责 XX”。这类空文件对 Claude 是有害的，它增加了规则数量，却没有提供可执行的约束。
每个子目录 CLAUDE.md 都应该有独属于该目录的硬规则。如果没有几条能明确指导行为的规则，就不应该创建这个文件。空文件的存在会让 Claude 以为“这个目录没有规范需要特别注意”，反而起了反效果。宁可让目录没有 CLAUDE.md，让顶层索引直接引导，也比放一个空壳强。
最后再分享一个小技巧
清理规则这件事，三个月做一次是合理的节奏。每次做的时候除了拆文件，顺手把已经失效的规则删掉。我常在清理时发现一些“远古规则”还在生效，比如某个早期版本限制用 Python 3.9 的语法，现在项目早就升到 3.11 了，这条规则已经完全没有意义，却还在浪费每一轮对话的上下文。定期删掉这些陈旧内容，比单纯拆文件更能让规则保持高权重。
CLAUDE.md 的终极目标不是把规则写全，而是让规则在正确的时机以正确的方式出现。顶层文件短小精悍，子目录文件按需加载，参考文档按路径引用，这一套组合拳下来，Claude 的执行质量提升是肉眼可见的。你现在就可以打开项目看一
