“祖传代码”这四个字，是从业者对遗留系统最客气的称呼。上周深夜有人发消息给我，说他接手了一个五年前的项目，仓库拉下来，README 六百字，三百字在讲怎么装环境，另外三百字介绍的是一个早就被删掉的模块。他问我：从哪开始读？这个问题几乎每周都会以不同形式出现——有人拿到外包交付的代码，有人要做二次开发，还有人是被临时抓去救火。共同点是：代码能跑，但没人说得清它是怎么跑的。

Zread 这类工具解决的正是这个卡点。它不修改你的代码，也不要求你先补一堆注释，而是把整个仓库当成输入，自动整理出一份结构化的可读文档：项目是干什么的、入口在哪、模块怎么划分、配置从哪来、关键流程怎么走、术语都指什么。对刚接手项目的人，这是最低成本的入场券；对长期维护的人，这是一次被迫的自我复盘。下面我按自己实际把这套流程跑通的顺序，从“为什么祖传代码难读”讲到“文档怎么活过三个月”，中间穿插具体的范围裁剪、参数设置、校对顺序和踩过的坑。

1. 祖传代码的真正门槛不在语法，在于没有地图

1.1 从“能跑”到“能改”之间，隔着一整套上下文

很多人以为读老代码慢是因为语言版本老、框架陌生、命名混乱。我做过几次统计，实际耗时占比最高的根本不是这些。打开一个陌生仓库，前两个小时基本消耗在找东西上：入口文件在哪、构建脚本是哪一个、配置文件有几份、哪份是线上在用的、依赖是锁死的还是浮动的、数据库表结构从哪来。这类信息在健康的项目里由文档承担，在祖传项目里通常由某个已经离职的人承担。

这就像进一栋没贴门牌的大楼，房间本身可能装修得很好，但你不知道哪扇门通向楼梯间。语法看不懂可以查，框架不熟可以学，唯独“这个函数在整个系统里处于什么位置”这类信息，没有任何搜索引擎能替你回答。工具生成文档的价值恰恰在这里——它先把门牌贴出来，哪怕贴得不全、有几处贴错了，也比完全没有强。

更麻烦的是隐性上下文。老项目里常有大量约定俗成的东西：某个目录必须按固定命名规则放文件，否则定时任务扫不到；某个配置项为空时走的是另一套默认逻辑；某个接口的超时时间写在注释里而不是配置里。这些内容不会出现在任何自动生成的概览里，但一旦你改动相关代码就会踩到。工具能帮你把这些位置标出来，让你知道哪些地方需要额外问人，这本身就是巨大的效率提升。

1.2 祖传项目的文档通常以三种方式失真

在动手生成新文档之前，先搞清楚旧文档为什么不可信，能省很多功夫。我把见过的失真形态归成三类，它们的处理方式完全不同。

• 时间错位：文档本身没写错，只是停留在三年前的架构上。原来的单体被拆过、某个模块被整体重写、部署方式从脚本换成了容器，文档一个字没改。这类最难判断，因为文字读起来通顺、结构完整，你会不自觉地信它。
• 注释自欺：代码里的注释写着“临时方案，后续重构”，而这个“临时”已经临时了四年。还有些注释描述的是函数原本的意图，实现被人改过好几轮，注释没跟上。这类失真最危险，它精确到行，误导性极强。
• 口头传承：压根没有文档，靠老员工口述。这类项目的知识高度集中在少数人身上，人一走就断档，但代码本身往往是自洽的，只是没人整理。

这三类的共同点是：不存在一份“和当前代码一致”的描述。所以重新生成一份文档，本质上不是锦上添花，而是重建一个可信基线。这个基线不需要完美，只需要明确标注出“这是在某次提交上生成的”，后续所有改动都有了对照物。

1.3 先画地图再读实现，收益差一个数量级

我试过两种读老项目的方式。第一种是从入口文件开始，一行行往下读，遇到函数就跳进去，读完再回来。这种方式读上三千行，脑子里全是碎片，对系统整体没有任何概念。第二种是先拿到一张粗略的结构图——有哪些顶层模块、谁依赖谁、数据从哪个入口进、从哪个出口出——再挑重点模块深入。

第二种方式的效率差距非常明显。原因是人脑处理信息依赖框架，有了框架，细节才能挂上去；没有框架，看一百个函数也是一百个孤立的函数。工具生成文档的最大贡献，就是在外围给你搭这个框架。它生成的模块说明可能只有一句话，甚至有一两句是错的，但已经足够让你知道“这个目录是干数据清洗的，那个目录是导出报表的”，从而决定先读哪、后读哪、哪些暂时不用碰。

所以我的建议很直接：接手新项目的前半天，不要打开任何源码文件，先把结构摸清楚。让工具生成文档、自己核对一遍模块划分、画一张十分钟能讲清的草图，再动手读代码。这半天投入换回来的是后面几周的方向感。

2. Zread 到底做了什么：从源码到可读文档的处理链路

2.1 输入是仓库，输出是给人读的路标

先把边界说清楚。这类工具的输入通常是一个代码仓库的快照——可以是本地目录，也可以是远程地址，可选指定分支或某个提交。输出不是 API 手册，也不是自动补全用的类型定义，而是一组面向“第一次接触这个项目的人”的说明材料。

我实际拿到的输出一般包含这几块：项目概览（技术栈、目录职责、启动方式）、模块清单（每个顶层目录干什么、对外暴露什么）、关键流程说明（几条主链路，比如“请求进来之后经过哪些层”）、配置项说明（有哪些配置、在哪读、影响什么）、术语表（项目内部的黑话对应什么概念）。有些实现还会附带问答式的检索入口，让人可以直接问“用户注册的逻辑在哪”。

提示：不同工具的具体输出格式差别很大，参数名和功能清单请以实际工具的说明为准。下面关于处理链路的描述，是基于这类代码文档生成工具常见实现方式做出的合理推断，用来帮助你理解“为什么某类内容容易生成错”，而不是产品说明书。

理解这条链路的意义在于：你能预判哪些部分可信度高、哪些部分需要重点核对。盲信生成结果的人，往往在“配置项含义”和“业务规则”这两块翻车。

2.2 采集与索引：先建结构，再谈理解

第一步是采集。工具会遍历仓库，跳过二进制和大体积产物，识别主要语言构成，读取依赖清单、构建脚本、配置文件、目录层级，有条件的话还会读取提交历史。这一步的产出是“这个仓库有什么”。

第二步是结构解析，也是整套流程里最硬的一环。它需要建立文件之间的依赖关系、识别每个文件对外暴露的符号（函数、类、常量、路由、组件）、再把这些符号之间的引用关系串起来，形成一张调用图。这一步做好了，后面生成的内容才有骨架；这一步做不好，输出就退化成“每个文件一句话摘要”的流水账，看着挺长，实际没用。

我在实际使用中最明显的感受是：索引质量决定了文档的天花板。同一个仓库，把构建产物和第三方依赖目录排除掉再跑，和直接对全量目录跑，结果完全是两个东西。后者会把大量样板代码当成核心逻辑，生成的模块说明里充斥着“该文件定义了若干工具函数”这类废话。原因很简单，索引阶段没有区分主次，语义归纳阶段自然抓不住重点。所以第三章我会花不少篇幅讲仓库净化，这一步的性价比比调任何参数都高。

2.3 语义归纳的分寸感：说多了是幻觉，说少了是废话

结构建好之后，进入语义归纳。工具会对关键文件做摘要，判断哪些是入口、哪些是核心业务、哪些是基础设施，然后组织成自然语言。这里的难度在于分寸：写得太细，容易越界，把“可能”说成“一定”，产生看似专业实则错误的描述；写得太粗，就变成目录的另一种排版形式，等于没写。

我见过效果比较好的输出，特征是“只描述能验证的东西”。比如它会写“该模块导出了三个处理函数，分别对应导入、校验、导出三类操作，被上层接口层调用”，而不会写“该模块负责保障数据质量”。前一句可以从代码里验证，后一句是脑补。反过来，效果差的输出往往充满后者：动词宏大、主语模糊、读完不知道具体做什么。

这也解释了为什么生成文档必须有人工校对环节。工具的强项是穷举和一致性——它不会漏掉任何一个目录，不会因为下班时间到了就草草收尾；弱项是业务判断——它不知道哪个模块是核心收入来源，也不知道哪个“临时兼容”的代码碰不得。校对的工作就是把工具看不见的那部分补上，同时删掉它过度发挥的那部分。

2.4 一份“人读得下去”的文档该长什么样

工具能生成很多内容，但全塞进一个文件里就是灾难。我在实际项目中会把输出拆成几个文件，各司其职，遵循“按阅读顺序组织，而不是按目录结构组织”的原则。目录结构是给机器看的，阅读顺序是给人看的，两者往往不一致。

docs/ ├── 00-项目速览.md # 一段话说明这是什么系统，给谁用，跑起来要几步 ├── 01-目录导览.md # 每个顶层目录一句话职责，标注"核心/基础设施/可忽略" ├── 02-启动与构建.md # 环境依赖、构建命令、常见启动失败原因 ├── 03-配置说明.md # 配置项清单、默认值、影响范围、修改风险 ├── 04-主流程拆解.md # 3-5 条核心链路，每条从入口到落库/返回 ├── 05-术语表.md # 项目内部黑话，人工维护，工具不覆盖 └── 99-生成说明.md # 生成工具、参数、基于哪次提交，方便复现

关键在于00-项目速览.md的写法。我要求它能在三百字内让一个完全不了解项目的人说出“这个系统大概干什么”。这一份写不好，后面的文件写得再详细也没人看。实际经验是，让工具生成初稿后手工重写这一段，比让它直接生成效果稳定得多——因为你比它更清楚这个系统在业务上到底承担什么角色。

3. 实操：把一个混乱仓库喂进去，文档怎么产出

3.1 喂进去之前先净化仓库，噪音会直接污染结论

这是整个流程里我最看重的一步。很多人第一次用这类工具，直接把仓库根目录丢进去，等十几分钟，拿到一份几十页的文档，翻了五页就再也没打开过。问题八成出在没有做仓库净化。

净化要解决的是“哪些代码不该进入分析范围”。我的处理清单大致是这样：

# 示意：分析前排除的目录类型，具体以工具支持的忽略规则为准 vendor/ # 第三方依赖，通常整体拷进来的 node_modules/ # 同上 dist/ build/ out/ # 构建产物，和源码高度重复 *.min.js # 压缩代码，分析价值为负 test/fixtures/ # 测试数据，容易混入假业务名词 migrations/ # 数据库迁移脚本，历史包袱极重，单独处理 docs/legacy/ # 旧文档，避免污染新结论 *.pb.go *.g.cs # 自动生成的代码

排除只是第一步，更重要的是范围裁剪。如果一个仓库有几十个顶层目录，我会先只选三到五个核心目录生成文档，其余暂时不碰。理由是：全量生成的文档读不完，读不完等于不存在。先覆盖核心，让团队先用起来，再逐步扩展，比一次性生成一份没人看的全集务实得多。

还有一个容易忽略的细节：不要用带未提交改动的本地目录去生成。工作区里的临时改动可能把某个函数注释掉了、把某个配置改成了本地地址，生成出来的文档和主干分支对不上，后面所有校对都白做。我的做法是从主干拉一个干净快照，在快照上跑，并在输出里记录对应的提交标识。

3.2 第一轮的粒度选择：按模块还是按入口

不同工具提供的粒度选项不一样，常见的两类是“按目录划分”和“按入口/流程划分”。我把两者的适用场景列一下，实际项目里往往需要混用：

我的默认策略是：第一轮先按目录模块跑一遍，拿到全貌，用它来判断哪些目录值得深挖；第二轮对识别出的三到五条核心链路按入口再跑一遍，生成主流程说明。两轮结果合并，前者当目录导览，后者当流程拆解，互补性很好。

参数上还有几个值得注意的点。输出语言建议直接选团队日常沟通用的语言，不要图省事用英文再翻译，术语对不上会让新人更困惑。分析深度如果可调，第一轮用浅档，先看结构对不对，确认范围没问题再加深，避免一上来等很久拿到一份方向就错的结果。

3.3 校对顺序：先信什么，后信什么

生成结果拿到手，千万不能从头到尾逐字读，那样校对时间和重新读代码差不多。我按“影响面 × 出错概率”排了个顺序，实测能省一半时间：

1. 先校启动与构建。这一段错得最多，也最影响信任。工具很容易把某个历史遗留的构建脚本当成主流程，或者漏掉一个必须手动执行的前置步骤。校对方法很土：照着文档在一个干净环境里走一遍，哪一步卡住就改哪一步。
2. 再校模块职责边界。重点看“这个目录是干什么的”这一句有没有跑偏，以及依赖方向有没有写反。依赖方向写反是最隐蔽的错误，会让读者对系统分层产生完全错误的印象。
3. 然后校核心链路顺序。主流程里各个步骤的先后关系，工具经常搞错，尤其是异步、回调、事件驱动的部分。校对时对照实际代码的调用点，把顺序捋直。
4. 最后才看细节。参数含义、返回值、异常分支这些，错了影响局部，不影响整体理解，放在最后批量处理。

注意：校对过程中不要边看边改文档，先把问题记在一个清单里，一次性回改。边看边改容易陷入局部，改到第十处时已经忘了第一处的上下文，最后前后矛盾。

还有个小技巧：校对时优先找“具体名词”，比如目录名、函数名、配置键名。这些是硬事实，对错一目了然。相比之下，“该模块负责数据清洗”这种描述性语句很难判断对错，容易看半天放过去。先把硬事实全核准，描述性语句的可信度自然就上来了。

3.4 输出落地：目录约定与“这是生成物”的标注

文档生成完，别散落在聊天记录或者某个人的本地目录里。我的做法是固定在仓库里划一个docs/generated/子目录，和手写文档物理隔离。隔离的原因很实际：生成物会被下一次生成覆盖，手写内容混进去就丢了。

每个生成文件头部固定加一段标注，写清楚生成工具、生成时间、基于哪个提交、用了什么参数。这段标注看起来啰嗦，实际价值在三个月后体现——当有人发现文档和代码对不上时，第一件事就是想知道这份文档有多旧。没有标注，他只能全盘不信；有了标注，他可以判断是“整体过期需要重跑”还是“局部漂移手工补一下就行”。

另外，生成物一定要进版本库，别只放在本地。我见过团队把生成结果放在某台机器的共享目录里，两个月后没人记得怎么重新生成，那台机器还被重装了。工具跑一次的成本不高，但“知道怎么跑”这件事如果不写下来，成本会高得离谱。把生成命令或者配置文件一起提交，是最省事的保险。

4. 生成文档的准确度：哪些地方一定会错，怎么验证

4.1 六类最容易生成错的内容，提前有个心理准备

用了这么久，我对工具的出错规律基本摸清了。下面这几类内容，我拿到结果时会重点看，其他部分可以快速扫过：

拿定时任务举例。一个服务里可能有五六个定时脚本，它们没有 HTTP 入口，也没有被任何地方显式调用，静态分析很容易把它们归类成“工具脚本”而忽略。但实际运维中，这些脚本往往是最关键的——数据对账、状态清理、报表生成全靠它们。校对时我会专门去搜一遍调度配置，把这类入口单独补进文档。

动态注册也是重灾区。有些框架靠扫描目录自动加载模块，代码里看不到任何 import 关系，工具自然画不出依赖链。这种情况只能人工补一段说明，写清楚“这个目录下的文件会被自动加载，命名必须符合什么规则”。这种约定恰恰是新人最容易踩坑的地方，写进文档价值极高。

4.2 三条交叉验证路径，比反复读文档靠谱

文档对不对，光读是读不出来的，必须拿别的信息源做交叉验证。我常用这三条：

第一条是跑测试。如果项目有测试用例，看测试覆盖了哪些模块，能快速判断哪些是核心、哪些是边缘。测试文件的命名和分布，本身就是一份隐含的模块划分说明。工具生成的模块清单如果和测试目录结构对不上，八成是有一方错了。

第二条是看运行时调用栈。挑一条文档里描述的核心链路，实际发一个请求或者跑一次任务，在关键位置打日志或打断点，把真实的调用顺序抓下来。这一步最费时间，但准确度最高。我一般只对最重要的一两条链路做，不追求全覆盖。

第三条是对照提交历史。看最近半年哪些文件改动最频繁，这些就是真正在维护的活跃区。工具生成的文档如果给某个三年没动过的目录写了很长的篇幅，说明它被目录结构误导了。反过来，如果某个高频改动的核心模块在文档里只有一句话，说明索引阶段漏了东西，需要回头检查排除规则。

这三条路径各有侧重：测试看结构，运行时看顺序，历史看权重。三条都对上的部分，基本可以放心用；三条里有一条对不上的，标记出来人工补。

4.3 文档和代码冲突时，永远信代码，但别急着删文档

总会遇到文档描述和代码实际行为不一致的情况。这时候我的处理原则很简单：以代码为准，但要搞清楚是哪一种不一致。

如果代码是新的、文档是旧的，直接改文档。如果代码里有绕过逻辑、临时补丁、环境判断分支，那就要把这段补进文档，而不是简单删掉。因为这类分支往往是最有价值的信息——它记录了某个历史问题的处理方式，后来者如果不了解，很可能把补丁当成冗余代码删掉，然后线上出问题。

还有一种情况是文档描述了一种“应该如此”的设计，而代码实现是另一种样子。这种最值得警惕，它可能意味着实现有缺陷，也可能意味着设计文档本身过时。我在实际项目中遇到过好几次，顺着这种不一致挖下去，找出了真正的逻辑漏洞。从这个角度看，生成文档不只是给新人看的，它也是一次对现有实现的体检——把工具生成的描述和代码逐条对照，本质上是在做一次低成本的代码审查。

5. 让文档活过三个月：维护机制比生成技巧更重要

5.1 把“重新生成”变成没人需要记得的事

所有文档都死在同一个地方：没人记得更新。生成文档尤其如此，因为它看起来是自动化的，大家会默认“它自己会更新”，实际上工具不会自己跑。

我的做法是把它挂到已有的流程节点上，不新增任何需要人记住的动作。常见的有两个挂载点：一是合并请求环节，当改动涉及核心目录时，触发一次重新生成并把差异贴到评审里；二是固定周期的定时任务，比如每周跑一次，生成结果有变化就提一个变更。前者保证及时性，后者保证兜底。

这两个挂载点的成本都不高，关键是配置一次之后就不用管了。相比之下，“约定每个月手动跑一次”这种方案我试过，第二个月就没人执行了。凡是依赖人记忆的维护机制，在长期项目里基本都会失效。

还有一点：重新生成之后要能看出变化。如果每次都整份覆盖、整份提交，评审时根本看不出改了什么，很快大家就会直接点通过。我的处理是让生成结果保持稳定排序，同样的输入产出同样的顺序，这样差异对比才有意义。这个细节看起来小，实际决定了文档更新会不会被认真对待。

5.2 术语表必须人工守，这是工具替代不了的部分

工具生成的文档里，术语表是最容易出问题的一块。原因是项目内部的黑话往往没有定义处——它可能来自某个业务方的叫法、某个历史系统的遗留命名、某次会议上的临时约定。代码里只有标识符，没有解释。

所以我的做法是：术语表单独一个文件，标记为人工维护，任何自动生成流程都不覆盖它。生成流程只负责往里面追加“发现的新词”，具体解释由人补。这样做的好处是术语表会随着项目演进持续增值，三年后它可能是整个文档里最有价值的部分。

实际补充术语时有个技巧：不要只写“X 是指什么”，要写“X 和 Y 的区别是什么”。新人困惑的往往不是单个词的含义，而是两个相似概念之间的边界。比如“订单”和“交易”在系统里是两个不同的实体，只在术语表里写各自的定义没用，写清楚“什么时候用哪个”才解决问题。

5.3 我踩过的四个坑，都是可以提前避开的

第一个坑：直接对全量仓库跑。第一次用的时候图省事，把根目录整个丢进去，等了很久，拿到一份几十页的文档，里面大段在描述第三方依赖的内部结构。后来加了排除规则、裁了范围，输出质量立刻不一样。这个坑的教训是：工具的输入质量决定输出质量，前期整理十分钟，后期省两小时。

第二个坑：没排除测试数据。有一次生成的术语表里出现了好几个根本不存在的业务名词，查了半天发现来自测试用的样例数据。这些假名词一旦流进正式文档，误导性极强，因为它看起来特别具体。后来我把测试数据目录统一排除，术语表改成人工维护，问题才解决。

第三个坑：生成的描述和团队口头叫法不一致。工具根据代码里的标识符生成模块名，但团队内部一直用另一套叫法。结果新人看文档学了一套词，开会时完全听不懂同事在说什么。解决办法是在术语表里做映射，把工具用词和团队用词并列写出来。这个成本很低，收益很高。

第四个坑：文档生成后没记录怎么生成。隔了三个月想更新，没人记得当时用的什么参数、跑在哪个分支上。重新摸索花了半天，还生成了一份风格完全不同的新文档，前后对不上。从那以后我强制要求把生成配置和命令一起提交，并在每个生成文件头部标注来源。

5.4 从文档再往前走一步：给新人的阅读路线图

文档写全了不等于好用。我观察过几个新人，拿到一份完整的项目文档，还是会问“那我先看哪”。这说明还缺一层东西：阅读路线。

我的做法是在速览文件里加一小节，写成“如果你要做 X，按这个顺序读”。比如“如果你要改一个接口的返回结构，先读接口层目录说明，再读对应的服务层模块，最后看数据访问层的字段映射”。这种路线三五条就够，覆盖最常见的几类任务。它的价值在于把静态的文档变成了可执行的路径，新人不需要自己规划，照着走就行。

这份路线图最好由刚上手的人来写，而不是由最熟悉系统的人写。熟悉的人会不自觉地跳过“显而易见”的步骤，而这些步骤恰恰是新人卡住的地方。让一个刚跑通流程的人记录下自己实际走过的顺序，往往比资深的人凭记忆总结更实用。

最后分享一个我在实际操作中的体会：这类工具最大的价值不是产出那份文档，而是逼着团队把散落在各处的隐性知识显性化一次。生成只是起点，校对和补充的过程才是真正的收获。一个项目如果连续两年没人能说清它的结构，那它的问题从来不是缺一份文档，而是缺一次认真的梳理。工具只是给了你一个不得不开始梳理的理由。