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.md2.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 Commitsfeat:、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 的执行质量提升是肉眼可见的。你现在就可以打开项目看一
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.md2.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 Commitsfeat:、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 的执行质量提升是肉眼可见的。你现在就可以打开项目看一
