CLAUDE.md 拆分指南：哪些规则该放子目录，哪些必须留根目录-北京尧图网络

CLAUDE.md 这件事我一开始其实没用对。最初只是在项目根目录随手记几条约定后来每个模块的注意点、每种任务的限制条件、每个踩过的坑都往里堆半年后那个文件直接飙到几百行。结果每次 Claude Code 启动都要把整份规则塞进上下文token 肉眼可见地涨更烦的是规则之间开始互相打架AI 的行为一会儿遵守这一条一会儿又按另一条来。后来我认真做了一次拆分把适合局部生效的规则下沉到子目录根目录只留真正的全局约束整个体验才正常回来。这篇文章就是把我拆分时的判断思路、目录设计、迁移步骤和排查过程完整整理一遍。核心解决一个问题CLAUDE.md 越写越长哪些规则该放到子目录哪些必须留在根目录。如果你现在也被一份臃肿的 CLAUDE.md 搞得焦头烂额这篇应该能直接给你一套可抄作业的方案。1. 为什么 CLAUDE.md 会越来越长加载机制与膨胀路径1.1 Claude Code 是如何读取 CLAUDE.md 的想拆好 CLAUDE.md得先弄清它的加载机制。Claude Code 不是只在启动时读一次根目录配置而是在不同层级都有自己可以“看见”的规则文件。从实测效果和社区讨论来看它通常会读取当前工作目录下的 CLAUDE.md并且当任务涉及某个子目录时该子目录里的 CLAUDE.md 也会被加载进上下文。也就是说一个项目里可以存在多份 CLAUDE.md各自管自己那一亩三分地。这个设计的本意很好让 AI 在不同的目录里拥有不同的“行为环境”。比如你在docs/下写文档和在src/下写代码需要遵守的约定本来就不同。但问题在于很多人包括当时的我压根没利用这个层级而是把所有要求全部堆在根目录里。根目录文件越来越长子目录却没有自己的规则文件AI 每处理一个文件都要背着整座大山。我后来给一个多模块项目重做配置时才意识到合理的 CLAUDE.md 不是一份“百科全书”而是一套“分层说明书”。根目录负责全局底线子目录负责局部细节两者各司其职AI 的上下文才能保持干净。1.2 文件膨胀的三个信号几百行的 CLAUDE.md 通常是慢慢膨胀出来的很少是一夜之间写成的。我归纳了三个典型信号供你对照检查。第一个信号核心规则被大量背景描述淹没。文件开头那一大段项目简介、技术栈说明、目录结构介绍占了很多篇幅但真正能约束 AI 行为的执行类规则只有一小部分。Claude Code 不是第一次接触这个项目的新人它不需要你科普什么是微前端它需要的是“这个仓库里必须怎么做”。第二个信号不同模块的专属约定全部混在一起。前端、后端、测试脚本、CI 流程的规则挤在一个文件里中间可能还夹杂着某个临时分支的特殊要求。AI 在处理后端任务时却被前端规范和临时约束干扰判断指令清晰度自然下降。第三个信号为了规避错误不断追加“不要做 XXX”的补丁式条目。这类规则多了以后很容易出现前后矛盾。比如根目录写“默认使用 pnpm 安装依赖”后面又因为某个特殊目录写过“该目录不要执行 pnpm install”两条规则同时存在AI 就会陷入选择困难。1.3 继续堆料的代价继续往一个文件里堆料代价是实打实的不是“读起来累”这么简单。第一是上下文膨胀。CLAUDE.md 里的内容会被当作指令送进模型上下文。模型每次回复前能携带的信息总量是有上限的你塞进去的规则越多留给任务本身的分析空间就越少。表现就是文件小的时候 AI 一次能准确改完三个文件文件大了以后它可能改一个文件就开始频忘记之前的约定。第二是规则冲突引发的行为漂移。同一个语义的规则在不同位置用不同语气写了两遍AI 不确定以哪个为准。今天它按根目录的“必须用 TypeScript 严格模式”做明天因为子目录里那句“该模块暂时不用严格模式”又放松了标准你每次都得检查结果反而更累。第三是维护成本高。想改一条通用规则你得先读一遍全文确认没有哪条子规则和它冲突测试时也很难判断 AI 的行为变化是因为规则生效还是因为它碰巧读到了某一段上下文。文件越长心智负担越重最后你宁愿多加一条规则也不愿意删一条旧规则恶性循环就开始了。2. 拆分规则前必须想清楚的一件事影响半径2.1 全局规则与局部规则的判断标准拆分不是把一个大文件剪成几份那么简单核心是先想清楚每条规则的“影响半径”。我的判断标准就一句话这条规则在离开它所在的目录后是否还应该继续生效如果答案是“应该”那它就是全局规则必须留在根目录或者通过显式导入让它能被所有任务看到。如果答案是“不应该”或者只对某一个目录、某一类任务有意义那它就是局部规则适合下沉到子目录。举个例子。规则“所有提交信息必须遵循 Conventional Commits 规范”这件事影响整个仓库任何目录的提交都得遵守它是全局规则。规则“packages/theme下的所有颜色变量必须从 tokens 里读取不允许硬编码”这件事只对packages/theme有意义放到根目录只会让其他模块的任务无谓读取它就是局部规则。这个判断标准看起来很简单但实际操作时很容易被“这个约定挺重要”的感觉带偏。重要不等于全局很多重要规则只对一个目录重要。2.2 给规则打上影响半径标签实际操作时我先把现有 CLAUDE.md 里每一条规则都复制出来单独打标签。标签分三类目录级、任务级、全局级。目录级规则约束的是某一个目录比如“src/api下的请求方法必须统一走httpClient封装”。任务级规则只在执行某类动作时生效比如“当你编写测试文件时必须使用describe.sequential避免并行冲突”。全局级规则则任何情况下都不能丢比如“禁止修改数据库迁移文件”“遇到不确定的命令必须先询问用户”。打标签的过程其实就能筛出一大批明显该下沉的规则。我当时整理完发现真正算得上全局的规则只占总数的三分之一左右其余都是目录级和任务级全堆在根目录里就是互相伤害。可以给你一张我当时用的判断表直接照着处理标签类型判断问题去向全局级移除这条规则后其他目录会出现行为失控吗留在根目录目录级只在某个目录下有约束力其他目录无关迁移到子目录 CLAUDE.md任务级只在执行某类任务时需要不影响日常代码生成留在根目录的 commands 区或迁移到任务相关目录过期/冗余已经没有项目场景支撑或被另一条规则覆盖直接删除2.3 先画出一张规则地图在动手改文件之前我强烈建议先画一张“规则地图”。不需要画得多精美也不用写代码就是把仓库的目录结构和现有规则之间的关系梳理出来。列出顶层目录比如src/、docs/、tests/、packages/每个目录旁边写上该目录涉及的所有规则。然后用箭头标出规则和目录的对应关系重复出现的规则圈出来明显冲突的规则单独列一个清单。这一步能直接帮你发现两件事第一哪些规则只属于某个叶子目录属于典型的待下沉对象第二哪些规则被多个目录共用说明它其实是全局规则不应该被拆进任何一个子目录。规则地图做好以后拆分方案基本就自动浮现了。后面写 CLAUDE.md 的时候你只需要照着地图走不会凭感觉瞎剪。3. 哪些规则适合放到子目录三类典型场景3.1 模块专属的代码约定第一类适合下沉的规则是模块专属的代码约定。举个例子我负责过一个带blog/目录的项目这个目录里全是活动落地页。它的代码约定非常有特色图片必须走 CDN不能直接引本地静态资源禁止引入非白名单的外部字体文案统一从copy/目录下的多语言文件读取不允许硬编码。这些规则对blog/目录来说是刚需但对其他模块没有任何意义。放在根目录 CLAUDE.md 里AI 在处理用户系统、订单系统的时候也会读到它们不但占 token还可能误以为“所有图片都要走 CDN”把普通后台页面的图片也改成 CDN 引用反而惹祸。把这类约定下沉到blog/CLAUDE.md后AI 只在处理 blog 相关文件时才会看到对应约束指令聚焦了很多。子目录文件里的写法我会保持“目录内语境”比如# blog 目录专用规则本目录下所有活动页组件必须遵守以下约定 - 图片资源一律使用 CDN 地址禁止直接引入 public/images 下未优化的原图。 - 字体只允许使用 fonts 白名单内的家族新增字体必须同步更新 copy/font-list.ts。 - 页面文案统一从 copy/ 读取禁止在组件里硬编码用户可见文案。3.2 特定工具链或任务流程第二类适合下沉的是特定工具链或任务流程。一个仓库里不同目录使用不同工具链太常见了尤其是 monorepo 结构里可能packages/core用 vitestpackages/legacy还在用 jestscripts/目录里则跑的是自定义 node 脚本。这种情况下子目录的 CLAUDE.md 可以写清楚“本目录测试命令使用 vitest不要执行 jest”“新增测试文件必须放在__tests__下”。这些细节如果放在根目录AI 很容易混淆不同目录的测试方式。我喜欢在根目录保留一条很短的桥接说明比如## 规则索引本仓库规则已按目录分层。进入 packages/worker 目录时请先读取该目录下的 CLAUDE.md其中包含 worker 模块专属的测试和构建约束。虽然理论上 Claude Code 会自动加载子目录 CLAUDE.md但桥接说明能帮它更快意识到“这个目录有额外规则”避免因为上下文切换而漏读。3.3 实验性、临时性约束第三类适合下沉的是实验性、临时性约束。这种规则通常生命周期很短只在一个分支、一个迭代或一段探索期内有效。比如某个新功能在做性能压测要求“禁止修改路由缓存策略”“暂时不要新增日志采样点”。这类约束如果放在根目录后面很容易忘记删除长期污染全局指令。我会把它放到功能所在目录的 CLAUDE.md 里文件顶部标注“This is temporary”等实验结束直接整份删除。举个例子# feature/perf-log 临时规则本目录规则自 2026-01 起有效性能实验结束后需整体移除。 - 禁止修改 logger 的采样率配置。 - 新增埋点必须走 trace 封装不允许直接调用底层上报接口。每次实验结束我只需要删除对应的子目录文件根目录完全不用动。这样既约束了 AI 在实验期间的改造行为又不会让临时规则残留到后续所有任务里。3.4 不适合下沉的反例下沉听起来很美好但也要说清楚反例。那种跨目录通用的约定比如“提交信息必须带类型前缀”“所有新代码都要加注释”“禁用any”如果贸然下沉到子目录会让不同目录的行为标准分裂。AI 在根目录工作时不知道这些约定在处理src/和docs/时也会执行不一样的规则这个项目就失去了统一的“底座”。我见过一个团队把“代码必须使用 pnpm 安装依赖”写进了frontend/CLAUDE.md结果 backend 目录没有这条规则AI 在 backend 里跑 npm install 时也没人拦着。这不算崩溃但明显不符合项目预期。全局规则下沉是最常见的一种拆错方式一定要避免。4. 哪些规则必须留在根目录全局规则保留清单4.1 影响所有子目录的编码规范根目录要保留的第一类规则是影响所有子目录的编码规范。这类规则是整个项目的地基不能因为切到子目录就失效。比如“项目统一使用 TypeScript 严格模式”“缩进统一两格”“禁止使用any”“文件名统一 kebab-case”等等。它们不针对某个具体模块而是定义一个仓库的“写作语言”。如果它们被移出根目录AI 在不同目录里看到的编码标准就不一致最后生成出来的代码风格会非常混乱。我自己的习惯是把这类规则放在根目录 CLAUDE.md 的最前面用最直接的语言表达不带任何修饰。因为它们是底线底线需要被反复看见。4.2 构建、测试、运行命令第二类必须留在根目录的是构建、测试、运行命令。根目录里的pnpm build、pnpm test、pnpm lint通常是一个仓库的总入口AI 在根目录启动任务时需要知道这些命令存在以及它们背后有什么限制。比如“build 之前必须先执行 typecheck”“测试前需要启动 mock 服务”“CI 环境不允许跑集成测试”。这些命令约束往往贯穿整个仓库如果只写在某个子目录AI 在根目录工作时就不会理解项目的全局执行链路。我一般会在根目录单独开一个“命令与执行约束”区把所有入口命令和它们的配套要求写在一起。4.3 AI 的行为边界与安全约束第三类也是我认为最不能下沉的一类是 AI 的行为边界与安全约束。比如“禁止执行删除数据库的操作”“遇到不确定的命令必须先询问用户”“不要修改node_modules或 lock 文件”“不要直接推送远端分支”。这类保护性规则必须全局生效。一旦下沉到子目录你在根目录工作时就等于没有保护AI 可能在一次普通重构中顺手改掉了不该动的文件。这类规则我建议放在根目录 CLAUDE.md 最显眼的位置甚至可以在开头加一个“安全红线”小节用强调语气写清楚。它们的价值不在于日常执行频率高而在于发生危险动作时能拦住 AI。4.4 高优先级的关键指令最后根目录还要保留少量高优先级的关键指令。所谓关键不是具体任务的描述而是那些你希望 AI 始终携带的元指令。比如“先用中文回答”“遇到报错先输出排查思路再动手改代码”“涉及多个文件时先列修改计划再执行”。这些规则不会随着目录切换而过时它们定义的是 AI 在这个项目里的协作方式。这类指令不需要多十条以内就够了放在根目录 CLAUDE.md 的最上方。如果根目录文件本身很长就把它们从后面的“项目细节区”里挪出来保证 AI 在任何上下文中都能优先看到。5. 子目录规则如何被加载优先级与合并策略5.1 自动加载与显式导入的区别要真正用好子目录规则得理解加载的两种方式。第一种是自动加载。Claude Code 在涉及某个目录时会尝试读取该目录下的 CLAUDE.md把里面的内容作为该子任务的额外上下文。这个机制的好处是自然AI 处理packages/worker下的代码时能自动看到 worker 的专属规则不需要额外指定。第二种是显式导入。你可以在根目录 CLAUDE.md 里用路径的形式把某个子文件引入比如packages/worker/CLAUDE.md。这样即使当前任务不在packages/worker目录下AI 也能在启动时看到这份规则。两种方式各有适用场景。自动加载适合局部生效不污染全局显式导入适合“你想让某份局部规则在特定场景下也能被全局看到”。比如一个子目录的规则非常重要任何涉及该目录文件的任务都必须提前知道那就在根目录显式引入一份。5.2 合并顺序与覆盖逻辑合并顺序是个容易踩坑的点。从实际表现看多层 CLAUDE.md 并不是简简单单地“后面的覆盖前面的”而是同时出现在上下文里共同约束 AI 行为。不存在一个明确的“子目录优先于根目录”的规则而是看具体规则的语言强度和执行场景。比如根目录写“默认使用 pnpm 安装依赖”子目录写“本目录必须使用 yarn 安装依赖”。AI 看到两条矛盾指令后有可能会因为子目录规则更具体、更接近当前操作而执行 yarn但它也可能因为根目录规则靠前、权重更高而继续用 pnpm。这个不确定就导致了行为漂移。所以最安全的做法不是依赖优先级而是避免覆盖。子目录不在根目录已有规则上搞“override”而是补充根目录没有覆盖的新细节。5.3 避免规则冲突的三个技巧在长期维护中我总结了三个避免冲突的实用技巧。第一在子目录 CLAUDE.md 开头加一句“顺位声明”。比如写“本目录规则是对根目录规则的补充。根目录已有约定不变与本目录不冲突时本目录规则优先。”这句话虽然不会真的改变加载顺序但能给 AI 一个明确的裁决依据减少模棱两可。第二删除重复规则而不是重写一遍。如果根目录已经有“禁止使用any”子目录就别再写“本目录禁止使用any”更不要写成“本目录不允许出现 any 类型”否则两份规则之间的措辞差异会让 AI 难以对齐。你可以在子目录里补一句“类型限制遵循根目录规则”然后集中写根目录没有的细节。第三用否定式表达减少歧义。比如“除非本目录明确允许否则不要使用npm”比“本目录使用pnpm”更清楚。因为否定式表达直接切断了其他所有可能AI 不需要判断npm算不算本目录约定。6. 从单一文件拆到子目录的完整实操过程6.1 第一步审计现有规则并分组现在说具体怎么动刀。第一步把现有 CLAUDE.md 完整复制到一个临时文档逐条审计。我的做法是每读一条就标注三个属性适用目录、适用任务、优先级。适用目录填“全部”或具体目录名适用任务填“所有任务”或“测试/构建/重构等”优先级填高、中、低。这个过程非常花时间但值得做。审计时还顺手做两件事清理已经过时的规则比如某个临时限制已经不需要了合并语义重复的规则比如“不要修改 lock 文件”和“禁止动 pnpm-lock.yaml”其实是同一件事只留一条。审计完你会得到三份清单全局保留列表、待下沉列表、待删除列表。这个时刻特别重要因为后面所有操作都是照着这三份清单走。6.2 第二步创建子目录 CLAUDE.md 并迁移第二步在目标子目录创建CLAUDE.md把待下沉的规则迁移进去。这里有个细节文件名一定是CLAUDE.md全大写不能叫claude.md或CLAUDE.MD。我之前就因为文件名写错导致 AI 一直没读到子目录规则排查了很久才发现是大小写问题。迁移时不要原样复制要根据该目录的实际情况改写得更具体。比如根目录里写着“前端组件要写测试”迁移到components/CLAUDE.md时可以改成“本目录下所有组件必须同时提交test.ts测试文件与组件文件同名放在__tests__下”。子目录规则越具体和根目录打架的概率越小。如果子目录结构很深是没有必要为每一层都建 CLAUDE.md 的。优先选择规则密度最高的那一层放置文件不要把同一份规则复制到多个层级。6.3 第三步根目录只留索引与桥接说明第三步重构根目录 CLAUDE.md。根目录保留真正的全局规则加上一份“规则索引”简单说明每个子目录有哪些专用规则。规则索引的价值在于AI 在根目录启动时能通过索引快速知道“这个项目有分层规则”而不是直接把所有内容读一遍才知道。它相当于给 AI 一张地图告诉它哪里有细节再决定具体要读哪一层。如果某些子目录经常在根目录任务里被触碰可以用显式导入把它引入根目录上下文。这样 AI 在根目录处理该子目录文件时也能提前知道对应规则。我的索引写法类似这样## 规则索引本仓库采用根目录子目录双层 CLAUDE.md 结构。 - packages/workerworker 模块专属测试与构建约束涉及该目录必须读取。 - frontend/活动页组件规范临时实验约束。 - 根目录以下规则为全局底线任何目录均不可违反。6.4 第四步验证规则是否按预期生效最后一步验证。我会先做一个最简单的测试在一个新会话里直接问 AI“根据当前目录下的 CLAUDE.md我的项目有哪些关键约束”看它能不能把根目录和对应子目录的规则都列出来。如果它只提到根目录完全没提子目录说明子目录规则没有被加载。接着再打开某个子目录里的文件让它解释该目录的专用规则。比如“这个packages/worker目录的测试规则是什么”如果它能准确说出“本目录测试命令用 vitest不用 jest”说明子目录 CLAUDE.md 生效了。验证时还要看一点AI 是否把根目录和子目录的规则混为一谈。如果它回答时把两个目录的规范并列在一起说说明它已经合并加载了这没问题。如果它拎不清哪些是全局、哪些是局部我会在子目录文件里再加一个“本目录特有约束”的分组让它更容易区分。7. 常见问题排查实录与避坑指南7.1 子目录规则偶尔失效是怎么回事这个问题我排查过好几次通常有三个原因。第一文件名写错。claude.md、CLAUDE.MD、Claude.md都可能不被识别。一定要确认是CLAUDE.md。第二文件位置太深或者被某些忽略规则挡住。部分项目结构里深层目录可能不在 Claude Code 的默认扫描范围需要把 CLAUDE.md 放到更上层的子目录或者用显式导入。第三当前任务根本不在那个目录下。比如你让 AI 修改src/下的文件它不会自动去读packages/worker/CLAUDE.md。如果一定要让某条规则在任意目录都生效就不该下沉应该留在根目录。排查的思路也很简单先用显式导入把子目录规则挂到根目录如果问题消失说明自动加载的触发条件没满足如果问题还在多半是文件内容本身有问题。7.2 同一条规则在两层重复声明会出现什么重复声明是最隐蔽的坑。理论上 AI 不会崩溃但用久了你会发现它的行为在不同会话里存在细微不一致。我踩过的例子是根目录写着“不要用require统一用import”某个子目录又因为历史原因写了一遍“本目录禁止使用require必须使用import”。AI 有时候遵守有时候不遵守执行结果随机性很大。原因就是它同时看到了两份含义相同但文本不同的规则不知道以哪一份为权威。解决办法很简单物理上只保留一份。根目录留子目录删除或者子目录留根目录删除。同时在另一份文件里用注释或索引说明“该规则已统一到某处”避免未来重新堆回去。7.3 有没有必要给每个子目录都放一个 CLAUDE.md没必要真没必要。我见过一种“为分层而分层”的做法为了显得规范每个目录都塞一个 CLAUDE.md结果大部分文件里只有两三句不痛不痒的套话比如“本目录是业务代码目录”“请遵循项目命名规范”。这些空话放到上下文里只会稀释真正重要的约束。我的原则是只有目录里有独有约定、独有命令或需要覆盖全局默认行为时才值得放。如果一个目录的规则和全局规则基本重合那就什么都不放让 AI 安心使用根目录规则就好。空文件不增加价值只增加 token。7.4 性能问题长文件真的拖慢会话启动吗这个得看实际影响但方向是对的。CLAUDE.md 的内容会进入上下文文件越长单次请求的 token 基数越大等待时间确实会上升。拆分之后根目录长度缩短日常启动和简单对话都更快。我拆完一个项目后明显感觉到 AI 的响应速度提升了一些尤其是我那个 root CLAUDE.md 从 400 多行降到 60 行之后。不过也要提醒一点子目录文件如果很多且 AI 在多目录间频繁切换它可能会把多份 CLAUDE.md 都读进上下文加载总量不一定减少。所以拆分的同时要顺手删冗余、合并同类项真正给文件“瘦身”而不是把一个大文件拆成五个中小文件就完事。8. 我的实际体会与三个实用建议如果你现在手里也有一份几百行的 CLAUDE.md我建议先别急着删用半天时间做一次规则审计把每条规则的适用目录标出来。拆完之后你会发现AI 在具体任务里的“听话程度”并不是靠规则数量堆出来的而是靠规则和目录的匹配度。规则越多AI 越容易混乱规则越精准AI 越容易执行到位。另外分享一个小技巧把“规则索引”放在根目录 CLAUDE.md 的第一行。我可以直接写“本项目规则已按目录分层请优先阅读各目录的 CLAUDE.md”这样 AI 在开始对话时就能意识到存在分层规则减少漏读。这个技巧我用了很长时间效果相当稳定。最后拆分不是一次性的动作。以后每新增一条规则先问自己一句“这条规则只对哪个目录有效”而不是顺手往根目录一贴。记住CLAUDE.md 不是备忘录它是 AI 的行为上下文。留得越精简越该出现的时候它就越可靠。

CLAUDE.md 拆分指南：哪些规则该放子目录，哪些必须留根目录

相关推荐

CLAUDE.md拆分手术：用三问法给AI规则分层，告别600行冗长配置

从单体到微服务：企业级架构演进与容器化实践

MySQL二进制数据读写与Android集成实战

更多资讯

水利数字化SCADA系统安全架构与国产化实践

前端工具函数实战：深拷贝、防抖节流与性能优化

paperclip 实战：Node.js + React 构建 AI Agent 框架

OpenSSL ENGINE 原理与加密卡算法卸载实践

AI工程从零构建：Python验证、TS契约、Rust加固的四阶演进

Agent 沙箱接入生产实践：选型、持久化与执行协议踩坑指南

今日更新

淘宝商品详情API开发实战与性能优化指南

Unity Package Manager刷新错误排查与解决方案

Java record 规范构造器能否被反序列化或反射绕过

本周精选

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

本月热门

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

基于DRV8818与STM32的双极步进电机驱动方案实战解析

DRV8818PWPR+PIC18F45K80双极步进电机控制方案实战

读完文章，想聊聊您的网站？