接手一个没有文档的老系统，我让AI把家底先摸清了

一、管理者最怕的那通电话

去年年底，团队接了一个其他部门移交的老系统。交接那天，对方发来一个压缩包：三十多万行代码，没有一行注释，架构文档停留在三年前，而且和现状对不上。写代码的两位同事一个已离职，一个在休长假。

移交后第二周，业务方来了需求：改一个计费逻辑。我安排了两个骨干去看代码，三天后他们给我的反馈是：「能改，但不敢保证不碰坏别的地方。」这句话在管理者耳朵里等于：这个系统的风险不可控。

我相信很多小团队的管理者都遇到过类似场景：

• 知识集中在个别人头上。谁懂这块代码，谁就是单点故障。
• 新人上手周期太长。招聘预算有限，招来的人一个月还在读代码。
• 改动前评估靠猜。需求评审时没人能准确说出某个模块的影响面。
• 文档是负债不是资产。写文档没人有空，写了很快就过时。

问题的本质不是「缺文档」，而是团队的认知和代码的实际状态之间有一个不断扩大的鸿沟，而且没有人力去填。

二、AI能在这个场景里做什么

我的判断是：让AI当「第一遍扫雷的工兵」，而不是「替代工程师的作者」。具体拆成三件事：

第一件：批量补注释。 AI阅读单个文件的成本几乎为零。让它逐文件读懂逻辑，输出函数级、模块级的注释，人只负责抽查。

第二件：产出架构说明草稿。 让AI从代码里反推模块划分、调用关系、数据流向，生成架构文档初稿，工程师在此基础上修正。初稿和空白文档之间，差的是整整一周的人天。

第三件：建立风险清单。 让AI标记出高风险点：无测试覆盖的核心逻辑、硬编码的配置、明显过时的写法。这份清单直接决定我后续排期的优先级。

这三件事共同指向一个管理目标：把「没人说得清」变成「有初稿可争论」。文档准确率不必一步到一百，但要先有一个能被团队批注、修正的对象。

三、我们实际跑的流程

整个流程我设计成四步，重点在流程和风控，而不是模型本身。

第一步：划定范围，控制输入粒度。 三十万行不可能一口气喂进去。我们按目录拆成约两百个「分析单元」，每个单元控制在模型上下文能完整容纳的规模。先让AI输出一份模块清单和依赖关系的总览，我据此确认分析顺序——从被依赖最多的核心模块开始。

第二步：分角色生成，而不是一次全生成。 同一份代码，我们让AI分别以三种角色输出三种产物：

1. 注释（面向未来读代码的人）
2. 模块说明（面向做需求评估的人）
3. 风险标记（面向做排期决策的我）

分开生成的质量明显高于一次生成混在一起的内容，也方便后续分别安排不同的人审核。

第三步：人机交叉审核，这是我作为管理者最看重的一环。 规则很明确：

• AI产出的一切内容默认「待验证」，不直接进代码库主分支。
• 注释由原模块的维护者抽查，核心计费模块100%人审，边缘工具类代码抽10%。
• 架构说明开会过一遍，任何人发现与事实不符当场批注。
• 所有AI生成的内容带上标记（比如文件头注明「AI生成，人工审核人：XXX」），将来发现错误能追溯到审核人。

第四步：把产物固化进流程。 注释合入代码库；架构文档进Wiki；风险清单变成季度重构候选列表。更重要的是，我们约定：今后新合入的代码，PR里必须带AI生成的注释，由reviewer确认。让这件事从「一次性运动」变成「持续机制」。

四、前后对比

效率层面：

数字是团队内部粗估，仅作量级参考，不同代码库差异会很大。

风险层面： 交接后我们最大的隐忧是「改动影响面不明」。AI标出的风险清单里有十多处无测试覆盖的核心逻辑，我们据此优先补了测试。下一个版本上线，回归缺陷明显减少——这个变化没法精确归因，但团队做需求评估时明显更有底气了。

协作层面： 以前需求评审会上，工程师说「这块我也不确定」的频率很高。现在大家会直接打开架构文档指着说「调用链在这里，影响面是这两个模块」。讨论的对象从「记忆和猜测」变成了「文档和批注」，会议时间缩短，扯皮也少了。

五、可直接复用的提示词模板

这是我们流程第二步用的核心模板，稍作修改即可用于你的代码库：

你是一位资深软件架构师，正在帮助团队为一个缺乏文档的遗留代码库补齐说明。

## 背景信息
- 技术栈：{{填写语言/框架/数据库}}
- 系统用途：{{一句话描述业务}}
- 本文件在整体中的位置：{{模块路径}}

## 你的任务（按顺序完成）
1. 为下列代码中每个函数/类添加中文注释：
   - 用途（一句话）
   - 参数与返回值中不直观的部分
   - 副作用（写库、发请求、改全局状态）
2. 总结本文件的核心职责，不超过5句话。
3. 标记你发现的风险点，每条注明行号和理由：
   - 硬编码配置/密钥
   - 无错误处理的IO操作
   - 可能的并发或事务问题
   - 明显过时或不安全的写法

## 输出要求
- 只输出你能从代码中确证的内容，不确定的地方明确写「待人工确认」
- 不要猜测不存在的业务背景
- 注释语言与代码库现有风格保持一致

## 代码如下
{{粘贴代码}}

模板里最关键的一条是「不确定的地方明确写待人工确认」。这把AI的幻觉问题从「隐藏的地雷」变成了「显式的待办」，审核效率高很多。

六、写在最后

工具方面，我们用的是支持长上下文的模型，配合团队现有的代码托管流程，接口调用费用以官网价格页为准。整个项目折算下来，成本远低于让两个骨干全职写一个月文档。

如果你想在自己团队复现这套流程，可以从一个中等规模的模块开始试点，跑通「生成—审核—固化」的闭环再推广。如果你还在挑选合适的模型服务，可以看看这个平台，注册入口在这里：https://api.thistoken.ai/register

老代码库不是包袱，缺的只是一份能让人快速读懂它的说明。这件事，AI替你把最贵的第一遍做完了。

---

本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。