02 蒸馏目标定义从仓库提炼什么、产出物清单这是《Git 仓库蒸馏术从代码仓库到 OpenClaw 虚拟人》系列的第 2 篇。第 01 篇讲了为什么需要蒸馏这一篇回答紧接着的问题到底要蒸馏什么在跑任何 git 命令之前先想清楚目标——否则你会被 8,000 次提交和 40 个模块淹没。一、先想清楚蒸馏不是把仓库全读一遍很多人听到仓库蒸馏第一反应是把仓库里所有东西都整理一遍。这是最大的误区。一个维护了 5 年的仓库包含8,000 次提交、40 个模块、20 万行代码3,000 个 issue、2,000 个 PR无数过期的注释和文档你不可能、也不需要把所有这些都蒸馏。蒸馏的本质是有选择地提取而选择的前提是——明确目标。这一篇的核心任务就是帮你回答三个问题从仓库中提炼什么蒸馏的 6 类内容产出物有哪些、优先级怎么排8 类产出物清单怎么根据团队需求确定蒸馏范围范围决策方法二、从仓库中提炼什么6 类核心内容仓库里的知识可以归纳为 6 大类。每一类对应一个知识问题蒸馏就是回答这些问题#内容类别回答的知识问题典型来源1架构系统现在长什么样模块怎么划分目录结构、依赖关系、import 图2演进系统是怎么一步步长成这样的commit 时间线、里程碑、重构记录3模式有哪些可复用的设计模式和最佳实践重复代码、惯用法、团队约定4决策为什么这么设计考虑过哪些方案commit message、PR 讨论、issue5API对外暴露了什么接口怎么用接口定义、类型声明、文档6技术债哪些地方是刻意留下的坑TODO、FIXME、workaround、hack2.1 架构系统的是什么架构蒸馏回答系统现在长什么样。这是最基础、也最容易被文档覆盖的一类——但正如第 01 篇所说文档会过期而从代码里蒸馏出来的架构是实时的。蒸馏架构不是画一张漂亮的架构图而是回答有哪些模块模块之间的依赖关系是什么是分层架构、微服务、还是单体 模块化核心业务逻辑在哪基础设施代码在哪哪些模块是核心资产哪些是历史包袱2.2 演进系统的怎么来的演进蒸馏回答系统是怎么一步步长成这样的。这是文档永远无法提供的知识——因为文档只记录现状不记录过程。从 commit 时间线里你能还原出项目从 0 到 1 的关键节点几次重大重构的来龙去脉架构从简单到复杂的演变路径哪些模块是后来加的哪些是一开始就在的演进知识对新人尤其宝贵——它解释了为什么代码长这样而不是让人对着现状瞎猜。2.3 模式系统的可复用资产模式蒸馏回答有哪些可以带走的东西。这是蒸馏中复用价值最高的一类。团队反复使用的设计模式工厂、策略、观察者……项目特有的惯用法错误处理方式、状态管理约定可复用的工具函数、公共组件团队约定俗成的代码规范模式蒸馏的产出是模式库——一份可以指导新代码怎么写、也可以让新人快速上手的资产。2.4 决策系统的为什么决策蒸馏回答为什么这么设计。这是隐性知识密度最高的一类也是蒸馏最有价值的部分。一个看起来不合理的设计背后往往有一个合理的历史原因当年为了赶上线用了一个临时方案后来一直没重构某个第三方库有 bug团队绕开了它用了 workaround业务需求变了但代码没跟上留下了历史遗留决策蒸馏把这些为什么从 commit、PR 讨论、issue 里挖出来整理成决策记录ADR——让后人不再对着代码猜。2.5 API系统的对外接口API 蒸馏回答系统对外暴露了什么、怎么用。这是消费频率最高的一类知识。对外提供的接口/服务清单每个接口的入参、出参、错误码调用方式、鉴权方式、限流规则版本演进哪些接口废弃了、哪些是新加的API 知识是团队协作的基础——前端要调后端接口、新模块要复用老模块的能力都依赖清晰的 API 认知。2.6 技术债系统的坑在哪技术债蒸馏回答哪些地方是刻意留下的坑。这是最容易被忽视、却最救命的一类知识。TODO/FIXME/HACK/workaround的分布哪些看起来该重构的地方其实不能动动了就崩哪些依赖是必须锁版本的升级会炸哪些模块是接手即地狱的需要特殊小心技术债知识让团队知道哪里能碰、哪里不能碰避免新人甚至老人踩进历史遗留的坑。三、产出物清单8 类可交付资产6 类内容蒸馏之后落地为 8 类产出物。每一类都有明确的消费场景和格式#产出物对应内容格式消费场景1仓库画像仓库结构、规模、元信息Markdown / 表格快速了解仓库全貌2演进报告提交历史、里程碑、重构脉络Markdown / 时间线理解项目发展轨迹3架构文档模块、依赖、架构模式Markdown / 图理解系统结构4知识摘要README、注释、issue、PR 精华Markdown快速获取隐性知识5模式库可复用设计模式、最佳实践Markdown / 代码片段指导新代码编写6决策记录ADR为什么这么设计Markdown / ADR 模板理解设计动机7知识图谱实体、关系、依赖可视化图 / JSON全局视角看系统8工具链方案git 命令 AI 工具组合Markdown / 脚本可复用的蒸馏流程3.1 优先级怎么排8 类产出物不是都要做也不是都要做到同样深度。优先级取决于团队当前最痛的问题团队痛点优先产出物原因新人 onboarding 慢仓库画像 架构文档 演进报告先让新人看懂再让新人敢改核心成员离职风险决策记录 知识摘要把脑子里的知识抢救成文档代码质量参差、重复造轮子模式库统一写法减少重复文档过期、没人信文档架构文档 API 清单从代码蒸馏实时准确历史包袱多、不敢动技术债清单 决策记录知道哪些坑不能踩一个判断原则如果一份产出物做出来团队里没人会去读、没人会去用那它就不该做。蒸馏的产出物必须有人消费否则就是自嗨。四、如何根据团队需求确定蒸馏范围蒸馏范围不是仓库有多大而是团队需要什么。用三步法确定范围第一步列出利益相关者谁会用蒸馏产物他们关心什么角色关心的问题需要的产出物新人系统怎么跑模块怎么分工仓库画像、架构文档维护者哪里能改哪里不能碰技术债清单、决策记录架构师架构是否合理演进方向架构文档、演进报告技术负责人有哪些可复用资产模式库、API 清单新项目团队能不能复用这个仓库的能力模式库、API 清单、知识图谱第二步确定蒸馏深度同一类产出物可以做到不同深度L1 概览级一页纸说清楚适合快速了解 L2 结构级模块 依赖 关键路径适合日常开发 L3 细节级逐模块深入 决策背景适合核心资产建议核心模块做到 L3一般模块做到 L2边缘模块 L1 即可。不要平均用力。第三步明确不做什么蒸馏范围要明确边界防止无限膨胀❌ 不蒸馏所有 commit只蒸馏有信息量的❌ 不蒸馏所有 issue只蒸馏有决策价值的❌ 不蒸馏所有代码只蒸馏有复用价值的❌ 不蒸馏所有历史只蒸馏对当前有意义的蒸馏是减法不是加法。做减法的标准是这份知识现在或可预见的未来会不会被用到用不到就不蒸馏。五、产出物驱动的大纲设计这个系列的 14 篇大纲就是产出物驱动设计的——每一章对应一个可交付产出01 为什么需要仓库蒸馏 → 认知为什么做 02 蒸馏目标定义 → 产出规划做什么 ← 本篇 03 仓库盘点 → 仓库画像产出物 1 04 提交历史挖掘 → 演进报告产出物 2 05 代码结构分析 → 架构文档产出物 3 06 文档蒸馏 → 知识摘要产出物 4 07 代码模式提炼 → 模式库产出物 5 08 决策记录生成 → 决策记录产出物 6 09 知识图谱构建 → 知识图谱产出物 7 10 蒸馏工具链 → 工具链方案产出物 8 11 OpenClaw 虚拟人机制 → 认知虚拟人是什么 12 蒸馏产物 → 虚拟人 → 虚拟人雏形memory skills 13 虚拟人落地 → 可用的仓库专家 14 实战案例与总结 → 全套模板这种产出物驱动的设计有一个好处每章结束你手里都多了一个能用的东西而不是又学了一堆概念。跟着系列走完你自然就攒齐了 8 类产出物 1 个虚拟人 1 套模板。5.1 一个可复用的蒸馏目标模板在开始蒸馏前建议先写一份蒸馏目标声明作为整个流程的锚点# 蒸馏目标声明 ## 仓库 - 名称xxx - 规模xx 万行 / xx 模块 / xx 年历史 ## 利益相关者 - 主要消费者新人 / 维护者 / 架构师 / 技术负责人 - 他们最痛的问题xxx ## 蒸馏范围 - 内容类别6 类中选架构、演进、模式、决策、API、技术债 - 深度核心模块 L3 / 一般模块 L2 / 边缘模块 L1 ## 产出物清单8 类中选 - [ ] 仓库画像优先级高 - [ ] 演进报告优先级中 - [ ] 架构文档优先级高 - [ ] 知识摘要优先级中 - [ ] 模式库优先级中 - [ ] 决策记录优先级高 - [ ] 知识图谱优先级低 - [ ] 工具链方案优先级中 ## 明确不做 - 不蒸馏xxx理由xxx ## 验收标准 - 蒸馏完成后团队能回答哪些问题 - 虚拟人上线后能回答哪些问题这份声明写清楚后后面 03~10 篇的每一步都有了该做什么、做到什么程度的依据。六、小结这一篇的核心就三句话蒸馏是减法从 6 类内容架构/演进/模式/决策/API/技术债中只选团队需要的。产出物驱动8 类产出物按优先级排每份产出物必须有人消费。范围要明确用利益相关者 → 深度 → 不做清单三步法防止蒸馏无限膨胀。下一篇我们开始动手[03 仓库盘点理解仓库结构与规模](03-Git 仓库蒸馏术从代码仓库到 OpenClaw 虚拟人-仓库盘点.md)——用git log、git shortlog、cloc、tree等命令先给仓库画一张画像。上一篇[01 为什么需要仓库蒸馏](01-Git 仓库蒸馏术从代码仓库到 OpenClaw 虚拟人-为什么需要仓库蒸馏.md)下一篇[03 仓库盘点理解仓库结构与规模](03-Git 仓库蒸馏术从代码仓库到 OpenClaw 虚拟人-仓库盘点.md)