接手一个五年没文档的老项目,AI帮我三天摸清了全部家底
你可能也遇到过这种事
去年年底,我接手了一个维护了五年的老项目。前任开发者早已离职,交接文档只有一个 README,里面写着「部署见 wiki」,而 wiki 链接已经 404。
代码本身倒是能跑,但问题在于:没人说得清它为什么这么写。三万行 Python,几十个模块互相调用,有些函数两百多行,唯一的注释是几处 # TODO: 后续优化——这个「后续」一等就是四年。
这种情况下,任何改动都是高风险操作。我当时的估算是:如果纯靠人肉读代码,摸清核心模块的调用关系和设计意图,至少需要三到四周。而排期只给了我一周期,其中还要留出做需求的时间。
如果这场景让你感到熟悉,那这篇文章就是写给你的。我最终用 AI 辅助的方式,把「理解老代码」这件事压缩到了三个工作日,而且产出的架构说明文档比人肉整理的更系统。
AI 在这件事上到底能做什么
先把 AI 能承担的工作列清楚,因为它能做的比很多人想象的多:
- 逐文件生成结构化注释:函数职责、参数含义、返回值、边界条件、已知副作用,按统一格式输出。
- 梳理模块依赖关系:读 import 和调用链,输出「谁依赖谁、为什么依赖」的说明。
- 识别隐性设计决策:比如某处加锁的原因、某个魔法数字的来源、某段「看起来多余」的代码实际是在兜底某个已知 bug。
- 生成架构说明文档:包括系统分层图(文字版)、核心数据流、启动流程、外部依赖清单。
- 标记风险点:硬编码配置、过时写法、无测试覆盖的关键路径——这些是后续重构的地图。
注意第 3 点。这是 AI 最容易被低估的能力。老代码里大量「为什么这么写」的信息,其实藏在代码模式本身里,AI 能从上下文推断出合理猜测,再由你确认。人肉读代码时,我们往往连「该问什么问题」都不知道。
我的实际流程
第一步:先让 AI 出一份全局地图
不要一上来就逐文件加注释。先把项目目录结构喂给 AI,让它产出一份模块清单和依赖概览。这一步的产出决定后面优先处理哪些文件——核心链路优先,边角工具类靠后。
第二步:分批投喂,逐模块生成注释
按模块拆分,每次投喂一个模块的代码,让 AI 输出结构化注释。关键约束是格式统一,否则最后拼起来会很难看。
第三步:让 AI 自己找疑点
注释生成后,我会追加一轮提问:「这个模块里有哪些你觉得意图不明确、或可能存在历史包袱的地方?」AI 会列出可疑点清单,我拿着清单去问老同事、查 git blame(好消息:git 历史还在),把答案补回文档。这一步 AI 出题、人答题,效率远高于人海捞针。
第四步:汇总成架构文档
把各模块的产出汇总,让 AI 生成最终的架构说明,再人工校对一遍事实性内容。
可复制的提示词模板
这是我在第二步用的核心模板,你可以直接拿去改:
你是一位资深代码考古专家。我会给你一个模块的源代码,
请为它生成结构化注释文档,输出格式如下:
## 模块概览
- 模块职责:(一句话)
- 对外暴露的接口:(列表)
- 内部依赖与外部依赖:(列表)
## 函数级注释
对每个函数,输出:
- 函数名与签名
- 职责:(一句话说清楚做什么)
- 参数说明:(每个参数的含义与格式)
- 返回值:
- 副作用与注意事项:(写文件、改全局状态、网络请求等)
- 意图存疑处:(如无法从上下文确定的写法,标注"待人工确认",不要编造)
## 风险标记
- 硬编码值、魔法数字、疑似过时写法、缺失的错误处理
要求:
1. 不确定的内容明确标注"待人工确认",严禁猜测后当作事实写出
2. 保持所有注释格式一致,便于后续合并
3. 使用中文输出
代码如下:
<在此粘贴代码>第 1 条要求很重要。AI 补注释最大的坑是「自信地编造意图」——把一个 bug 说成设计。强制它标注不确定项,可以把幻觉变成待办清单。
前后对比:数字说话
以这个三万行的项目为参照:
| 工作项 | 纯人工估算 | AI 辅助实际 | 节省 |
|---|---|---|---|
| 模块依赖梳理 | 4-5 天 | 0.5 天 | ~90% |
| 全量函数注释 | 8-10 天 | 1.5 天(含人工抽查) | ~80% |
| 架构说明文档 | 2-3 天 | 0.5 天 | ~80% |
| 风险点排查 | 2 天 | 0.5 天 | ~75% |
| 合计 | 16-20 天 | 3 天 | ~80% |
成本方面,三万行代码的处理涉及的 token 量不小,具体花费取决于你选的模型和用量,以官网价格页为准。但可以确定的是:即便用较贵的模型,总成本也远低于开发者两周的人天开销。省下的时间我用来做了两件更有价值的事:给核心链路补测试,以及和业务方对齐了后续的重构边界。
另一个不容易量化的收益:产出的文档是格式统一的。人肉写注释,写到第三天就开始偷懒;AI 不会。
几条实战经验
- 小批量投喂。一次塞一整个项目,AI 会顾此失彼,输出质量明显下降。按模块分批,质量稳定得多。
- 人工抽查不可省。我会对每个模块随机抽两三个函数核对注释,发现编造立即返工。这是守住质量底线的关键动作。
- git 历史是黄金搭档。AI 标注的「待人工确认」项,一半以上能通过 git log 和提交信息直接找到答案。
- 文档要回流进仓库。把 AI 产出的说明放进
docs/并纳入 review,否则下一个人接手时,你就是在制造新的「老项目」。
写在最后
老代码库的文档欠账,过去是「知道该还,但永远排不上期」的债。AI 把还债成本压到了原来的五分之一以下,这件事从「应该做」变成了「顺手就做」。
如果你想自己跑一遍这个流程,可以试试接入 API 自己搭流水线,批量处理整个仓库会比手动在对话框里粘贴高效得多。注册入口在这里:https://api.thistoken.ai/register ——拿到 key 之后,上面那个提示词模板稍加改造就能直接跑批。
---
想直接跑通示例?访问 https://api.thistoken.ai/register 注册 ThisToken.AI,获取 API Key 后即可开始。