十万行祖传代码没人敢动——我作为技术负责人，用AI补齐注释与架构说明的一次流程化尝试
一、管理者面对的现实痛点
团队接手了一个运行八年的老系统。原核心开发早已离职，代码里几乎没有注释，文档停留在三年前的半成品状态。新成员入职后平均要花几周才能独立改一个模块，而每次改动都可能牵一发动全身——因为没人能说清模块之间的依赖关系。
作为管理者，我面对的不是“代码写得好不好”的问题，而是三个流程性问题：
- 知识集中在少数老员工脑子里，人一休假，迭代就停摆。
- 改动风险评估靠拍脑袋，没有架构说明，评审会上大家只能凭记忆猜影响面。
- 新人培养成本高，带一个人等于让他把代码从头读一遍，这是纯消耗。
补注释、写架构文档这件事，人人知道该做，但永远排不进迭代。因为它是“重要不紧急”，而且工作量巨大、枯燥，没人愿意干。这正是AI该接手的场景。
二、我们怎么把这件事做成流程
直接把整个代码库丢给AI是不现实的。我们把它拆成了四步，每一步都有人的审核点，这是风险控制的关键。
第一步：分模块、分批次喂给AI。 按目录拆分，每次只处理一个模块，避免上下文超限，也方便验收。接入模型时我们走的是统一网关（相关平台的接入费用以官网价格页为准），方便控制用量、按模块核算成本。
第二步：AI生成，人定格式标准。 我们先让AI按统一模板输出：模块职责、对外接口、依赖关系、关键业务规则、潜在风险点。格式统一了，后续才能汇编成一份可检索的文档库。
第三步：老员工做事实校验。 AI生成的注释和说明可能存在“看起来很对其实是编的”的情况，尤其是业务规则部分。我们安排熟悉系统的人只做校验，不做编写——工作量从“写文档”降到“改文档”，老员工接受度很高。
第四步：归档进知识库，纳入评审流程。 生成的架构说明成为代码评审和新需求评估的必读材料，文档不再是一次性交付物，而是流程的一部分。
三、核心提示词模板
这是我们实际使用的模块级分析提示词，可直接复制修改：
你是一位资深架构师，请分析我提供的代码模块，输出中文文档，严格按以下结构：
# 模块名：<根据代码推断>
1. 模块职责：用3句话以内概括这个模块解决什么业务问题
2. 对外接口：列出主要公开函数/类，说明输入、输出、副作用
3. 依赖关系：它依赖哪些模块、被哪些模块依赖（从import和调用推断）
4. 核心业务规则：提炼代码中隐含的业务逻辑，标注对应的代码位置
5. 潜在风险点：指出可能有问题的地方，如硬编码、隐藏副作用、边界缺失
6. 给新人的导读：建议的阅读顺序和理解要点
要求：
- 不确定的内容明确标注「推测」，不要编造业务背景
- 涉及外部调用（数据库、接口、消息队列）请单独列出
代码如下：
<粘贴模块代码>其中“标注推测、不要编造”这一条是血泪教训——早期版本没写，AI会给一些不存在的业务背景编出煞有介事的解释。
四、用AI前后的对比
改造前：
- 新人熟悉一个模块约需一到两周，主要靠自己啃代码。
- 改动评审靠老员工记忆，影响面判断出现过遗漏，导致过一次线上回滚。
- 文档更新无人负责，写一次烂一次。
改造后：
- 新人先读AI生成、人工校验过的模块说明，熟悉周期明显缩短，深度的理解仍需读码，但起点高了很多。
- 每次改动前先查依赖关系清单，评审会上讨论的是“清单上哪几项受影响”，而不是“大家记得还有谁调用了它”。
- 文档维护被拆成“AI生成+人工校验”两个轻量环节，可以按需触发——比如一次大重构后，重跑一遍模块分析即可。
需要诚实说明的是：AI补齐的不是“全部知识”，那些真正只在人脑里的历史决策（比如“当年为什么这么设计”）仍然需要访谈老员工补充。AI做的是把“能从代码读出来的部分”自动化，这一部分占了整个知识缺口的大头。
五、管理者的三点风险提醒
- 不要跳过人工校验环节。 AI生成的注释如果错了，比没有注释危害更大——它会以确定性的口吻误导后来者。
- 控制成本与节奏。 分批处理、走统一网关计费，才能避免一次性token消耗失控，也便于向管理层汇报投入产出。
- 把产出物嵌进流程。 文档不进评审流程，三个月后又是一堆过期废纸。
如果你也想低成本试水这类AI能力，可以从统一接入平台开始，按模块小步跑：https://api.thistoken.ai/register
---
本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。