CLAUDE.md 持续膨胀时，规则该如何分配到子目录？

团队在同一仓库持续补充开发约定时，CLAUDE.md 很容易从简短入口膨胀成覆盖所有环节的操作手册。真正需要解决的并不是文件行数，而是每条规则应在什么任务中出现。下面将围绕根级约束、子目录说明、路径条件和流程手册，分析它们各自适合承载的内容。

CLAUDE.md 越写越长，哪些规则该放到子目录？

一个前后端放在同一仓库的团队，最初只在 CLAUDE.md 里写了测试入口和提交要求。几个月后，文件里又出现接口错误码、组件样式、数据库迁移、版本发布、事故恢复。维护者让 Claude Code 改一个按钮的文案，它却同时拿到了后端事务说明和发版步骤。

于是，团队把大文件拆成五份，在根文件逐一用 @ 导入。目录看上去清爽了，可每次会话要读的内容未必减少。这是本文的教学情境，没有对应的客户端实跑记录。它要解决的问题也很具体：一条规则应该在哪种任务中出现，才能及时提供必要信息，同时避免把所有操作手册都变成每次任务的前置材料？

前一篇讨论两种客户端如何共享项目事实；这一篇只讨论 Claude Code 内部的组织方式，不把它推广成所有 Agent 的加载规则。机制依据核验于 2026 年 9 月 18 日。示例目录、命令及测试方案由作者设计，不能当作任何真实项目的现成配置。

1. 拆成多个文件，不等于改成按需读取

Claude Code 文档明确区分了几种情况：@ 导入展开内容；没有 paths 的 rules 在启动时加载；带路径条件的规则则在读取匹配文件时触发。把长文件分成短文件，只有改变了加载条件，才改变了内容进入上下文的时机。官方说明：指令与路径规则

假设原来的根文件包含四类说明。第一类是“不要手改生成的客户端代码”；第二类是“接口变更需要检查错误结构”；第三类是“组件改动要检查键盘操作”；第四类是十几步的版本发布流程。它们都可能重要，但重要性并不能决定是否每次都加载。前三类分别对应全仓约束、后端任务和前端任务；第四类只在发版时使用。

如果维护者把它们分别命名为 common.md、backend.md、frontend.md、release.md，再全部导入根文件，主要收益是方便分工编辑。它没有回答“改按钮时是否需要发布流程”。相反，文件越多，读者越难直接看出一个入口究竟拉进多少材料。

这里不应急着追求最短的根文件。假如仓库只有一个服务，几条命令和一段约束已经足够，拆分可能只是多几个跳转。需要调整的是某条说明的适用范围，而不是把行数本身当作质量指标。把仍然适用于全仓的要求移走，也可能让入口短了、任务反而缺少必要前提。

我们先选一个具体任务来判断：修改 apps/api/src/orders.py，为重复订单返回明确错误。这个任务需要知道后端入口、错误结构和相关测试；如果改动涉及共享接口定义，还要知道客户端代码怎样生成。它不需要仅因同处一个仓库，就预先掌握所有前端布局规范和完整发版过程。

2. 先让目录表达任务边界，再选择文件放法

下面是教学仓库的既有目录，而不是要求读者照建一个 Monorepo。这里的 Monorepo 指多个应用或模块在同一个版本库维护。

sample-shop/
├── CLAUDE.md
├── apps/
│   ├── api/
│   │   ├── CLAUDE.md
│   │   ├── src/orders.py
│   │   └── tests/test_orders.py
│   └── web/
│       └── src/OrderButton.tsx
├── packages/contracts/order.schema.json
├── generated/client/
├── .claude/rules/
│   └── web-ui.md
└── docs/release-runbook.md

根文件可以保留三项共同事实：生成客户端以接口定义为源；修改共享契约需要检查两个应用；交付时要说明实际运行了什么检查以及未覆盖的部分。这些要求影响跨模块决策，若只藏在后端目录，处理接口定义的人未必能及时看到。

apps/api/CLAUDE.md 则说明后端差异，例如在什么目录运行订单测试、已有错误封装在哪里、哪些调用必须共用事务。这里写的应是读者容易错过而且确实稳定的约定，不必重新介绍根文件已经说明的生成目录和全仓交付要求。

子目录文件的存在，并不意味着它在任意会话开始时都已经生效。官方的大型仓库指南区分启动位置和后续读取：祖先链上的指令与访问子目录时发现的指令，不是同一次发现动作。团队应把启动目录纳入验证条件，而不是只检查文件放没放对。官方指南：大型仓库中的指令组织

因此，在根目录启动后询问“你知道后端约定吗”，不是可靠的验收任务。更好的教学任务是要求读取订单实现与测试，再提出修复计划。这样，任务确实经过后端文件，维护者也能查看实际读取范围与计划是否一致。另一条测试从 apps/api/ 启动，用来观察入口改变后的差异；两条记录不能混成一次成功。

维护者还要抵制“子目录天然覆盖根规则”的想象。本文的做法是让根规则写清适用范围，局部文件只补充差异。比如根文件写“变更哪个应用，运行那个应用的验证；共享契约变更检查两个应用”，后端文件再给出后端命令。不要一边在根文件要求所有任务运行全部测试，一边在子目录又写只运行单元测试，然后指望模型替团队裁决正策冲突。

3. 跨目录的同类文件，用路径条件表达

后端规则按应用目录组织很自然，但前端说明有时横跨应用和共享组件。此时，单靠文件所在目录未必能准确表达范围。路径规则把“适用于哪些文件”写进规则元数据，更适合这种情况。

在教学仓库的 .claude/rules/web-ui.md 中，可以写成：

---
paths:
  - "apps/web/src/**/*.tsx"
---

# Web 界面改动

保留现有键盘交互和可访问名称。
涉及交互时，先查看相邻测试；在 apps/web 运行项目约定的界面检查。
仅改静态文案时，说明哪些交互检查没有执行，不把未运行写成通过。

这个示例故意只匹配一个实际目录。若仓库新增 packages/ui/，需要核对实际文件位置，再把对应模式加入同一规则。不能只因为文件后缀相同，就把 **/*.tsx 当作必然正确的全仓范围；教学站点、旧应用和主应用可能使用不同约定。

另外，给文件起名 web-ui.md，或者把它放进 .claude/rules/frontend/，主要是在帮助人分类。是否具有路径条件，要看 paths，不能靠目录名字猜。规则的触发与读取匹配文件有关，不应把它理解成每次工具调用前必经的校验器。官方路径规则示例

对订单错误修复而言，这意味着前端要求什么时候相关，取决于任务实际涉及哪些文件。如果后端响应改变迫使前端调整提示信息，那么两类规则都相关；正确目标不是坚决不加载前端规范，而是在需要修改界面时及时取得它。

反过来，若 Agent 为了解仓库而广泛读取前端代码，前端规则也可能进入这次会话。路径条件不是“后台自动判断任务所属团队”的标签系统。我们能控制的是模式和任务入口，不能仅凭路径分组就承诺上下文永远只包含一个模块的说明，更不能据此给出节省多少 Token 的数字。

还有一种容易漏掉的情况：规则只匹配实现，却没有覆盖独立修改测试的任务。维护者应问清楚这条要求约束的是实现语言、业务模块，还是验证过程。如果要求针对所有后端工作，应考虑测试目录；如果它只针对某种组件实现，就不应为求保鲜扩大到全部文件。范围扩大和范围遗漏都有成本。

4. 发布手册不必成为每次任务的背景

现在回看十几步的发布流程。它涉及版本准备、变更说明、制品核对和回退安排，是一个有明确开始与结束的任务。把全文塞进根规则，会让普通修复会话承担它的阅读成本；只写一句“发布要谨慎”，又丢掉了操作细节。

对于这种过程性材料，可以保留独立手册，需要重复调用时再考虑 Skill。Claude Code 的 Skills 文档允许把任务说明与配套资料组织在一起，并区分由用户调用和由模型选择调用的方式。它适合封装特定工作流程，但“封装成 Skill”本身不等于执行得到批准。官方说明：Skills

本例先保留 docs/release-runbook.md，根文件只说明“发版任务先读该手册；实际发布另需批准”。暂不编写一个会运行发布命令的 Skill。这样既能说明材料在哪里，又不会因为演示一个文件结构，就偷偷引入外部写操作。等团队确认该流程确实反复使用，再考虑把读取手册、收集版本信息、形成检查报告的步骤封装起来。

如果以后制作用户主动调用的发布检查 Skill，可以研究 disable-model-invocation: true，让它不由模型自行选用；但这仍不能替代发布系统的权限控制。本文只用它解释调用条件，不提供可以直接用于生产环境的发布脚本。软件权限、自动化检查与自然语言要求承担不同职责，不能相互抵账。官方机制对照

同理，自动记忆可以帮助保留会话中积累的经验，却不适合被当作团队唯一的规范存档。假如“发布前需要检查数据迁移”是所有维护者都必须知道的要求，它应有可审查的团队来源，而不是只留在某位使用者的本地经验中。这是组织责任的选择，不能靠“工具应该记住了”来保证新同事也能得到相同信息。

我们没有必要一开始就把根指令、子目录、路径规则、Skills 和自动记忆全部用上。对于本例，根文件加一份后端局部说明、一份前端路径规则和一份按任务读取的手册，已经能表达实际差异。额外机制只有在解决新的问题时才值得加入。

5. 用三个任务检查迁移，而不是数少了多少行

完成整理后，主要交付物是一张规则去向表。表中的“读取时机”是待验证的设计意图，不能自动当作运行结果。

原说明	本例去向	应在哪种任务中取得
生成客户端与共享契约边界	根 CLAUDE.md	所有可能修改相关资产的任务
订单错误结构与后端检查入口	apps/api/CLAUDE.md	读取并修改后端文件的任务
界面键盘交互与组件检查	带 paths 的 web-ui.md	读取匹配界面文件的任务
多步骤发布与回退手册	docs/release-runbook.md	明确的发版准备任务

表写好后，先核对每条原有有效要求是否有去向。特别要找那些看似属于局部、实际影响公共资产的要求。生成目录约束就是一个例子：后端开发者最熟悉它，却不意味着只有后端任务才需要知道它。不能为了实现“根文件只留几行”的目标，把跨模块约束一并搬走。

接着在固定提交、客户端版本和配置下，用新会话分别检查三个任务。第一项只改按钮文案，记录读取了哪些文件，以及界面规则是否出现；第二项修复订单错误，记录后端约定和对应检查；第三项调整共享契约，观察是否识别需要考虑两个应用，而不是机械地归入后端。

每个任务都要同时保留来源与动作。可以结合客户端提供的上下文查看能力核对加载文件，再检查实际使用的命令和修改范围。让模型复述一段规范只能作为线索；它既不能证明约定来自预期文件，也不能证明约定已经被执行。测试报告最好逐项写出已检查、未检查与受环境限制的部分，避免把一个模糊的“遵守了规则”当作结论。

如果前端任务没有获得规则，先看它有没有读取匹配路径、模式是否正确、项目配置是否允许加载；如果后端任务带入许多无关说明，先追根入口的导入和实际读取范围。不要立即再添加一句“请务必遵守规则”：那可能只是把发现机制的问题误判成了措辞问题。

迁移也应可回退。保留修改前文件与去向表，分一批迁移一类规则，确认没有遗漏再删旧正文。若使用旧会话验证，新旧内容可能都在上下文中，结果难以解释；若同时换模型、改提示、调整权限和拆文件，也很难判断是哪一项改变导致差异。因此，本例优先固定条件，先验证规则分配是否正确，不同时宣称任务效果提升。

本文没有运行这组三任务，也没有提供节省 Token 或成功率改善的统计。对团队而言，先拿到一份能够逐条追踪、能在真实任务里核验的规则去向表，比得到一个看上去很简洁但不知道遗漏了什么的目录树更有用。

下一次给 CLAUDE.md 增加一段文字时，可以先问：哪些任务必须知道它，什么时候需要读到它，谁负责维护它？答案是“所有任务”的，考虑根入口；答案指向局部代码的，选择明确的目录或路径条件；答案是一整套操作过程的，保留可按任务读取的手册。文件拆分完成之后，真正需要验收的是这些条件是否把信息送到了需要它的任务里。