CLAUDE.md拆分手术：用三问法给AI规则分层，告别600行冗长配置-北京尧图网络

最近接手一个维护了半年多的项目打开根目录CLAUDE.md的瞬间我就有点想退出去——600 多行从数据库表结构到 commit message 格式再到老支付模块不要动这种一次性警告全堆在同一个文件里。更麻烦的是这份超长记忆会被塞进每一次会话的上下文Claude 每轮对话都背着这堆东西干活响应慢不说规则还经常互相打架。这篇文章就聊聊我怎么给一份臃肿的CLAUDE.md做拆分手术以及哪些规则值得放到子目录去。如果你的项目也出现了类似症状——CLAUDE.md越来越长、Claude 开始忽略某些规则、或者你改一处规则要费半天劲去翻它到底写在哪——那你大概率需要重新规划规则文件的分层结构。下面这些内容来自我真实的迁移经历可以直接拿去用。1. 膨胀到 600 行的根目录文件我从一次重构里看到的典型病灶先说说我接手时那份文件的具体情况你对照着看自己是不是也中了。当时根目录CLAUDE.md里什么都有.github工作流说明、Docker 启动命令、支付模块的表结构、前端组件命名规范、日志字段要求、甚至还有一条周三晚上不要跑全量测试的临时提醒。表面上看起来是记录得越全越好实际上这种写法有三个很现实的问题。第一是上下文成本。Claude Code 在每次对话里都会把根目录的CLAUDE.md作为基础记忆加载进来。600 行换算成 token 是个不小的数字这些 token 会占据每一轮响应的注意力预算。Claude 不是读一遍就完而是在处理任何任务时都背着这些内容。结果就是你让它写一个简单的工具函数它脑子里还装着支付模块的几十条旧规则写出来的东西经常用力过猛甚至还做过好心办坏事——严格按照某条过时规则渲染了早已不存在的字段。第二是规则冲突。根目录里既有全局约定又有某个子模块的特殊约定两者还没写清楚优先级。比如根目录写着统一使用 axios 发起请求前端子目录又写着本模块所有请求走封装的 fetchClaude 在改前端代码时就会陷入纠结有时候听根目录的有时候听子目录的全看上下文里哪句话离得更近。规则越多这种看心情执行的情况越严重。第三是维护成本。当你想查某条规则为什么存在时根本找不到责任人和时间线。文件被改了许多轮有些规则早就失效了但没人删新规则看到旧规则还在又不好意思覆盖就这样一层层叠上去。到后面已经不是配置文件而是一份没人敢动的历史档案。所以你如果发现根目录CLAUDE.md超过了一定体量不要急着在里面继续加内容先停下来想想哪些内容真的需要全项目可见哪些内容其实只对某个目录有意义。这才是拆分的起点。2. 靠上下文吃饭的工具加载机制先搞清楚再谈拆分在动手拆之前我花了一天重新读了一遍记忆文件的加载规则。这不是浪费时间——如果你不理解 Claude Code 是怎么读取这些文件的拆出来的结果大概率是看起来整洁了实际更乱了。2.1 根目录是常驻子目录是按需翻页我自己的实测感受是Claude Code 在启动项目时会把根目录的CLAUDE.md读进上下文作为整个会话的基础指导。当工作目录切到某个子项目或者任务明显涉及某个子目录时它还会额外读取该目录下的CLAUDE.md。换句话说根目录文件是常态常驻的子目录文件是按需加载的。这个差异非常关键。放在根目录的规则代价是每一次对话都承担好处是任何场景都不会漏。放在子目录的规则代价是只有涉及到这个目录时才会被读取好处是不会污染其他场景的上下文。所以拆分的核心思路不是把文件弄短而是让规则在正确的时间出现在正确的位置。2.2 引用与通配符CLAUDE.md 本来就可以当索引用官方文档提供了两个处理长配置的机制一个是用符号引用其他文件一个是用#加 glob 表达式批量匹配文件。这两个机制是我这次拆分的主要工具。引用的意思是你可以在任意一个CLAUDE.md里写docs/architecture.md让 Claude 在加载这个CLAUDE.md时把对应文件也并入参考。这特别适合放那些长度大、但没必要全文灌进上下文的文档——比如架构说明、API 列表。引用进来后 Claude 会按需查阅而不是像常驻规则一样每轮都占据上下文。#通配符则适合想按目录批量生效的场景。比如# services/*/CLAUDE.md这种写法可以让你在根目录里统一声明所有服务模块的规则文件都生效。不过在实际使用中我发现通配符的优先级和冲突处理比单个引用更复杂普通项目用引用加目录级CLAUDE.md基本就够用了没必要追求花哨。2.3 别忘了上下文预算越长的常驻内容越会被平均化对待还有一个我后来才意识到的问题上下文里的内容不是均匀生效的。根目录文件越长Claude 在回答问题时的注意力就越分散。它会把每一条规则都当成同等重要的背景信息结果没有一条能真正进入它的核心决策回路。这就好比开会时给每个人发了一本 600 页的规章制度然后问你今天下午的改版方案要做哪些兼容大部分人都会愣住。规则需要的不是都在场而是用得上的时候在场。所以上下文预算本质上比文件行数更重要。把低频规则从根目录挪走不仅是为了让根目录短一点更是为了让剩下那些高频规则获得更高的权重。3. 下沉还是留守我给每条规则定的三个判定问题有了机制认知就可以开始给规则分类了。我总结了一套三个问题的判定法每次遇到一条规则就依次过一遍基本能决定它是去是留。3.1 作用范围是判定第一权重第一个问题是这条规则出了当前目录还有效吗如果答案是依然有效它就必须待在根目录。比如不允许直接修改 generated 目录下的文件所有提交必须通过测试这类铁律不管改哪个模块都得遵守放进任何子目录都会出问题。子目录规则有一个隐含假设它只在 Claude 进入该目录或处理该目录任务时被读取。一旦你处理其他模块这条规则就相当于不存在。反过来如果一条规则只在某个目录内有意义它就不该留在根目录。比如支付模块的对账接口幂等键必填——这个约束对订单模块没意义对前端更没意义它留在根目录只会浪费上下文还容易让 Claude 在处理其他任务时过度遵守平白多做很多无用检查。我自己的标准是如果这条规则能在离开这个目录后依然合理成立那它大概率属于根目录如果它是这个目录的专属常识那就下沉。规则的作用范围永远是第一权重其他问题都要排在它后面。3.2 变更频率是第二判定因素第二个问题是这条规则最近半年改过几次规则也会过期。数据库字段会变、接口协议会改、团队成员会调整约定。如果一条规则经常更新比如某模块的建表规范每两三个月就要变动一次那把它放在根目录的代价就很大——每次改动都触发根目录文件变更而根目录文件是全局常驻的任何微小的调整都会被所有会话感知这等于让一个高频变化的变量去影响所有下游行为。所以变更频率高的规则更适合隔离到子目录。这样你改的是局部记忆Claude 只在相关任务中用到新版本不会因为根目录频繁变化导致其他场景的行为也跟着抖动。像前端组件目录结构某个服务的启动参数这类三周一小改、半年一大改的内容往下沉准没错。3.3 体积和优先级互相牵制第三个问题是这条规则有多大它是指导还是参考体积大的内容比如完整的数据库 schema、接口字段对照表、部署环境清单这些属于参考数据。它们往往有几百行但真正使用频率很低只在特定任务中需要。这类内容放进根目录是典型的高成本低收益正确做法是放进子目录的 CLAUDE.md或者拆成独立文档再用引用。优先级高的内容则相反。像绝对不能删除的历史数据表生产环境禁止执行某命令这种红线规则哪怕只有几行也必须留在根目录并且要放在靠前的位置。Claude Code 读取记忆文件时通常更关注靠前的内容优先级最高的全局红线值得占据这个位置。我用一张表来总结判定逻辑你可以打印出来贴在手边规则类型放根目录放子目录原因全局红线是否任何模块都必须遵守且优先级最高跨模块工作流命令是否高频、通用、影响全局模块内部约定否是出模块即失效留守浪费上下文大段参考数据否是体积大、低频使用应按需加载高频变更规则否是隔离变动避免全局上下文抖动作用范围模糊的规则暂留根目录暂留根目录先观察实测后再决定4. 一次完整的拆分手术从审计到验收的全过程理论讲完下面是我实际操作时走的完整流程。我拿一个典型的服务端前端基础设施项目举例你照着步骤走就行。4.1 先给现有规则做户口普查第一步不是动手删而是先把整个CLAUDE.md通读一遍给每条规则建立一条记录。我建议用表格记录四个字段规则原文摘要、它写在哪个位置、它到底管哪个模块、最近一次变更是什么时候。你不一定要专门写文档直接从 git 历史里看这个文件的 commit 记录就能拼出大致时间线。这一步会非常直观地暴露问题。我盘点时发现600 行里真正属于全局规则的不到 80 行其余 500 多行全是某个子目录的专属约定、历史遗留的临时警告、还有几条完全重复的配置。这个比例本身就说明拆分势在必行。4.2 先砍后搬先合后拆盘点完之后先做减法再做移动。减法包括三类内容已经失效的规则、被新规则完全覆盖的旧规则、纯流水账式的日志记录。这些直接删掉不要犹豫。然后做合并。有些规则在不同位置重复出现比如根目录写了services/的端口约定子目录文件里又写了一遍而且内容一致。这类重复规则合并成一条放在更具体的位置上。最后才做拆解和移动。我的顺序是先建子目录文件把要下沉的内容移进去再把根目录里剩余的内容压缩成总纲索引结构最后逐条验证。千万不要反过来先删根目录再建子目录那样容易漏掉内容而且一旦 Claude 的行为异常你根本分不清是删漏了还是搬家搬坏了。4.3 落地实例拆分前后的目录与文件内容拆分前的目录大致长这样project/ ├── CLAUDE.md # 600 行什么都有 ├── services/ │ ├── order/ │ │ ├── src/ │ │ └── tests/ │ └── payment/ │ ├── src/ │ └── tests/ ├── frontend/ │ └── src/ └── infra/ └── deploy/拆分后变成了这样project/ ├── CLAUDE.md # 60 行全局总纲子模块索引 ├── services/ │ ├── order/ │ │ └── CLAUDE.md # 订单模块专属规则 │ └── payment/ │ └── CLAUDE.md # 支付模块专属规则 ├── frontend/ │ └── CLAUDE.md # 前端约定 └── infra/ └── CLAUDE.md # 部署与运维命令根目录文件被压缩成类似这样# 项目总纲 ## 全局红线 - 不允许修改 generated/ 下的文件 - 生产环境禁止执行任何删除操作 - 所有改动必须通过测试后再提交 ## 通用约定 - 代码风格遵循根目录 .editorconfig - commit message 使用 Conventional Commits 格式 ## 子模块规则索引 - 订单服务见 services/order/CLAUDE.md - 支付服务见 services/payment/CLAUDE.md - 前端项目见 frontend/CLAUDE.md - 部署与运维见 infra/CLAUDE.md而支付模块的services/payment/CLAUDE.md则放了这些内容# 支付模块规则 ## 核心约束 - 改动用有状态事务禁止裸 SQL 提交 - 对账接口必须携带幂等键 idempotency_key - 日志必须带上 request_id方便链路追踪 - 所有金额字段统一使用分为单位禁止使用浮点 ## 遗留警告 - 老支付通道已冻结不要新接入第三方网关 - 退款回调的验签逻辑暂时不要重构等新键盘上线再说看见没有根目录只保留了全局铁律和我去哪里找更具体的规则这个索引信息。Claude 在处理支付相关任务时会因为进了services/payment目录而加载对应的CLAUDE.md拿到那几条专属约束。而在处理订单、前端或运维任务时它完全不用背支付模块那堆东西。4.4 验收用三组对话确认改造有效搬家完成后必须验收不能只看文件结构。我习惯用三组对话来验证。第一组让 Claude 处理一个子目录专属任务。比如在支付目录下问它这个模块的退款流程要注意什么看它的回答是否包含子目录文件里的规则。第二组让 Claude 处理一个与子目录无关的任务。比如让它看一下根目录的 README 然后写个总结看它是否还会主动提起支付模块的旧规则——如果提了说明根目录里还有漏网之鱼。第三组故意给一个会触发全局红线的场景比如让它修改generated/下的文件听它是否会主动拒绝。如果三组对话都符合预期这次拆分才算真正成功。5. 拆分后最容易踩的五个坑我逐个踩过再讲五个我在拆分过程中真实踩过的坑。这些坑不是理论推演是花了不少时间填出来的。5.1 全局铁律被误放进子目录AI 在模块外直接失忆第一次拆分时我把所有新代码禁止使用某旧依赖库这条规则放在了frontend/CLAUDE.md里。结果没过两天我让 Claude 在services/order里帮忙处理一个脚本它毫不犹豫地在后端代码里用了那个库还写得振振有词。原因很简单这条规则是全局的不只属于前端。它应该在根目录而不是任何一个子目录。所以我把这条规则单独抽出来加了醒目标注放回根目录最前面。现在我对带所有、任何、一律这类词的规则格外敏感凡是带全局量词的规则一律先假设它属于根目录直到找到充分理由再放下去。5.2 同一主题在两级文件里各写一遍冲突不可避免第二个坑是根目录和子目录针对同一件事各写了一条规则而且细节不一致。比如根目录里写了时间字段统一使用 dayjs 处理支付模块的子目录文件里又写了本模块只能使用原生 Date。Claude 在处理支付任务时两条规则都能读到表现就成了猜硬币——有时候走 dayjs有时候走原生 Date完全不可控。解决思路是重新约定优先级根目录只写基础共识子目录写例外和覆盖一旦子目录要覆盖全局规则必须显式说明本模块例外以本条为准。这样 Claude 至少能分清哪个是默认、哪个是特例不会因为两条规则并列而随机执行。5.3 搬家时把引用路径直接照抄结果看起来对但没生效根目录里原本有docs/order-api.md这种引用搬进services/order/CLAUDE.md的时候我直接原样复制。结果实际对话里 Claude 并没有读取到被引用文件的内容排查了半天才发现是路径解析的基准变了。这个坑我最想提醒你每个CLAUDE.md文件里的引用路径在搬家后都要重新确认基准不能靠肉眼判断。我当时用了个笨办法——搬完后逐个文件让 Claude 说出被引用文档的第一行内容如果它说得出来说明加载成功如果支支吾吾或开始编造就赶紧检查路径。后来我干脆在子目录文件里统一写以本文件所在目录为基准的路径并且搬家后每一条引用都实测一遍。5

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

相关推荐

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

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

低功耗WiFi+BLE模组接入智能家居生态：SDK移植与配网认证实战

更多资讯

水利数字化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双极步进电机控制方案实战

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