把 CLAUDE.md 拆成「精简入口 + 模块化 skill 文档」的通用方法论｜开发实践

项目的 CLAUDE.md 一开始是「一页总览」，写来写去就膨胀成了一本找不到重点的说明书：架构、每个模块的细节、部署步骤、历史决策、踩坑清单全堆在一起。等你需要查一个具体问题时，得在几百行里来回扫；新人照着读也看不出优先级，更难分辨哪些还没过期。更麻烦的是，文档越长，越没人维护——一旦模块改动，没几个人敢去动那一大坨。

这套困境不是某个项目独有，几乎所有叙事型工程文档都会走到这一步。这篇文章沉淀的是一套通用的拆分方法论：把一份臃肿的总览 CLAUDE.md，重构成「精简总览入口 + 一组按领域拆分的模块化 skill 文档」。它不绑定任何特定技术栈或项目，可以作为你重写任意仓库文档时的模板重复使用。

为什么要拆：总览与细节不该混在一起

一份健康的项目文档应该回答同一类问题的人聚在一起。可现实是，总览页把三种完全不同的读者混在了一起：

• 刚上手的人只需要一句话定位、怎么跑起来、有哪些红线；
• 老手查细节要的是某个模块的实现、已知坑、配置在哪儿改；
• 维护者改代码要的是某个环境的部署差异和报错怎么排。

把这三类需求压进一个文件，收益率会迅速降低：总览越来越厚，细节越来越难找，双方都痛苦。拆分的本质是给每个使用场景一个独立入口，让「我要做什么」决定我该读哪个文件，而不是从头把整本翻完。

拆分模式的蓝图

拆分后形成三层结构，各司其职：

第一层是精简的 CLAUDE.md 总览。它只留四类东西：

• 项目一句话定位 + 技术栈 / 架构清单；
• 最常用的命令（耦合到具体环境的，例如要切到哪个目录、用什么工具启动）；
• 硬性红线约定（哪些不能改、哪些方向必须遵守）；
• 一张「我在做什么 → 读哪个文档」的导航表。

除此之外的深度细节，全部下沉到第二层——一组按领域拆分的模块化 skill 文档，每份只讲一个领域，通过导航表互相引用。最后还有第三层，一份 README 索引，把所有 skill 文件列全并各配一句定位，供新手或新会话快速落位。

就这么一层「总览只留骨架、细节全部下沉、索引统领全部」。

翻转视角：按「任务」而非「文档名」来索引

这个模式最关键的一步，是把导航表从「按文档名组织」翻成「按任务组织」。人不会每次都记得「有个叫 xxx-reference 的文件」，但一定知道自己「正在做的事」：

索引的价值不在于「能不能找到」，而在于「从我想做的事到文件，只需一眼」。这是这套模式区别于简单「分文件」的分水岭——它默认了用户几乎总带着任务来，而不是带着文档名来。

每份 skill 文档的「固定骨架」

拆分不是把原文按章节乱剪拼贴，而是给每份文档立一套固定骨架，保证它们风格统一、信息不散：

1. 适用场景（Scope）——一句话说清「我在做什么任务时该读这份」。
2. 关键概念 / 机制说明——该领域的核心设计、交互流程、组织方式，配一张精炼的流程图或调用链。
3. 具体操作 / 实现路径——清单式步骤，含路径、命令、示例代码，能照着做。
4. 已知陷阱 / 注意事项——该领域最容易踩的坑、边界行为、容易误改的地方，单独成节，不打散。
5. 变功耗点（可选）——当该领域存在两种或多种等价写法 / 变体时，讲怎么取舍。
6. 交叉引用——文末列出相关的其他 skill 文档名，方便顺着读。

这个骨架是「怎么写项目文档」的一份通用蓝图，任何一个刚分出来的 skill 都能直接套。

拆分更要补：总览里没有、但高价值的五类内容

拆分绝不是机械截断——它是一次「借机补齐总览缺失项」的机会。这批文档如果项目里还没有，建议在建每份 skill 时补上：

一、反向上手索引。 如果用户只记得一个模糊的手法词、一个符号，却不记得文档名，怎么办？每个 skill 开头都要一条「让你一眼找到我」的入口，把常用别名、关键词对齐到本文件。

二、调用链 / 依赖关系。 文档里补一句「它依赖谁、被谁依赖」。脱离调用上下文，一个孤立的 API 会很难理解。

三、可复核清单。 每份文档附「做完这段应该确认什么」的验收项，替代靠叙述片段拼出整体认知。

四、环境差异提示。 明确标注「本地 / 部署 / 测试」三套路径下，行为各不一致。

五、文档时效性标签。 每份都标注它是「随历史沉淀的参考档案」还是「维护中的活文档」，一旦代码与文档冲突，以代码 + 总览 + skill 为准。

硬性约束：冲突优先级和「只读历史」

拆分整套方式时还要定三条纪律，否则很容易在复用中失控：

• 历史设计沉淀类文档（旧计划、旧 specs、旧方案报告）默认「仅供参考」。 默认不改，只允许新增 skill 或更新 skill 索引。
• 冲突推定：文档描述与代码冲突时，一律以「代码 + 总览 CLAUDE.md + skill」为准。 文档会随迭代过期，代码不会。
• 每份 skill 只维护自己的交叉引用表；索引一旦改动，其余对该文档的引用要同步。 防止互联文档互相破坏。

产出流程与心得沉淀

拆分不要一上来就写文件，分两步走：

第一步，先给交付方案。 列出结构树 + 每份文件的「职责、包含章节、在代码里覆盖的范围」清单，跟用户对齐后再动笔。

第二步，拆分前先记录问答。 把用户拆分前抛出的问题、以及你的回答逐条记录下来，归入对应章节——这些是拆分「为什么这么设计」的第一手材料，不能丢；等文档写完一两个月再看，正是这些当时看来无关紧要的对答，让后来者明白当初为什么做出了某个决定。

方案定了再实际写文件。

结论

把 CLAUDE.md 拆成「精简总览 + 模块化 skill 文档」，本质是一次按任务域的再排布：拆的关键不只是分文件，而是三件事：导航从「按文档名」翻到「按任务」、每份文档用固定骨架保证整体一致、顺手补齐总览容易缺的信息。 结构上始终让「总览管骨架、skill 管细节、索引管落位」三权分治，任何项目都能套用。本文从中提炼出的是一套概念层的用法，不绑定任何具体技术栈——你用 Web 写代码、用什么框架部署都不受影响，直接复制这套骨架即可。

完整提示词：一条可直接复用的文档拆分指令

上面这套方法论，用一句话很难塞进去，拆成一份内容完整、能直接粘贴给 Claude的提示词会更好用。下面这段是以本方法为基础的「拆分 AGENT」，把「为什么要拆、怎么拆、每份长什么样、红线纪律、先对齐再动手」一次性交代清楚。需要重构某份臃肿的项目文档时，把 <仓库说明>、<文档路径>、<历史问答> 三项替换掉，其余原样发送即可：

你是一名工程文档架构师。目标是把我仓库里一份**过度膨胀的总览文档**，重构成「精简总览入口 + 一组按领域拆分的模块化 skill 文档」。

## 背景
- 仓库：<一句话说明项目是做什么的、技术栈（如 Spring Boot + Vue，或纯 Node/纯脚本）>
- 待拆文档：<CLAUDE.md 或 README.md 等，给出精确路径>
- 本次的「为什么」：总览页混进了三种读者——刚上手的人、老手查细节、维护者改代码，导致收益率急剧下降，新人照读看不出优先级，老手找不到具体细节，文档越长越没人维护。

## 目标结构（三层，各司其职）
1. 精简总览：只留四类——项目一句话定位 + 技术栈/架构清单；最常用命令（耦合到具体执行的）；硬性红线约定；一张「我在做什么 → 读哪个文档」的导航表。其余深度细节全部下沉。
2. 一组按领域拆分的模块化 skill 文档（放到 .claude/skills/ 或 docs/<领域>.md），每份只讲一个领域，通过导航表互相引用。
3. 一份 README 索引：把所有子文档列全，每份配一句「在什么任务时读」。

## 强制点
- 导航表必须「按任务」组织，不要「按文档名」：用户基本带着任务来，不带文档名来。
- 每份子文档用固定骨架：1）适用场景一句话；2）核心概念/机制（配精简调用链）；3）具体操作/实现清单（含路径命令示例）；4）已知陷阱；5）变功耗点（可选）；6）交叉引用。全文通用、全文件可套、全文风格统一。
- 除拆骨架外，**顺手补全总览缺的高价值内容**：反向上手索引（记住模糊字也能找到）、此文档依赖谁被谁依赖、执行完成的复查清单、本地/部署/测试环境差异、文档时效性标注（历史档案还是维护中的活文档）。

## 三类纪律
- 历史设计文档（旧计划 / 旧 specs / 旧方案报告）默认只读，只允许新增 skill、更新索引，不改旧内容。
- 文档与代码冲突时，一律以「代码 + 总览 + skill」为准。
- 每份子文档只维护自己的交叉引用，改了索引必须同步它处引用，防止文档互相破坏。

## 流程（两步走，先给方案再动手）
- 第一步：先给出交付方案，不要直接写文件。列出结构树 + 每份文档的责任、纳入章节、对应在代码里覆盖的范围，给我确认。
- 第二步：动手前先记录我的问题与你的回答，归到对应文档的对应章节（这份“为什么”是第一手资料，别丢）。
- 确认后再实际创建/改动文件，保持既有文件编码与仓库内已有的注释语言约定。

写完后，不要立即发布、不要推、不要调任何接口，把结果列给我看就好。
```

用这份提示词时，把 `<` 开头那几处占位符替换成真实信息即可。拆完记得顺手跑一遍导航表，确认「从想问的事到文件，只需一眼」。