接手了一个没人敢动的老系统之后，我把注释和架构文档这件事交给了AI
一个管理者的困境
去年年底，团队接手了一套运行了七年的核心业务系统。原维护团队只剩一个人，且即将离职。留给我们的是：三十多万行代码、零星的中文注释、一份五年前的Word版架构图，以及那句经典的交接台词——“逻辑都在代码里”。
作为小团队的负责人，我最担心的不是代码写得差，而是知识只存在于某个人脑子里。新人不敢改，老人不敢碰，每次发版都像拆弹。如果花两个月让两个资深工程师纯手工梳理文档，业务排期根本不允许；但如果不管，技术债会越滚越大，人员流动时风险完全不可控。
我需要的不是“AI帮我写代码”，而是AI帮我把已有代码的知识显性化，变成团队共同资产。
先想清楚流程，再动手
我的原则是：AI不直接改代码，只产出“文档层”的东西——注释、模块说明、架构图、调用关系清单。这样即使AI出错，也不会污染生产代码，风险可控。整体流程分五步：
第一步，划定范围与优先级。 不是所有代码都值得补注释。我让团队先列出高风险模块：改动频繁的、出过线上事故的、有外部依赖的。总共圈出六个核心模块，约八万行。
第二步，喂上下文。 把模块代码分批交给AI（长上下文模型，如 Claude、DeepSeek、GPT 系列），同时附上数据库表结构和已有的零散文档。切分粒度以“一个完整模块”为单位，太碎会丢上下文，太大则超出窗口。
第三步，AI初稿，人评审。 AI产出的注释和架构说明，必须由熟悉业务的工程师过一遍。AI常犯的错误是：把“现状”当成“设计意图”，比如某段明显是补丁式的丑陋代码，AI会煞有介事地解释它“为了优雅地处理边界情况”。评审的价值就在这里——把AI猜错的地方纠正过来。
第四步，文档入库，进版本管理。 AI产出的所有文档和代码仓库放在一起，走正常 code review 流程合并。文档从此和代码同生命周期。
第五步，建立增量机制。 定一条团队规矩：新代码合并时，提交人负责让AI同步更新对应模块的架构说明。补文档不是一次性运动，而是持续流程。
可复制的提示词模板
这是我们实际使用、迭代了三轮后的模板，供参考：
你是一位资深软件架构师，正在帮助团队补齐遗留系统的文档。
# 角色
- 你只输出文档，不修改任何代码逻辑
- 你区分「代码做了什么」（事实）和「推测的设计意图」（需标注[推测]）
# 任务
1. 为下列代码补齐中文注释：
- 每个文件顶部：模块职责、依赖关系、被谁调用
- 每个函数：功能、入参出参含义、副作用、已知风险点
2. 输出一份模块级架构说明，包含：
- 核心数据流（输入从哪来、处理过程、输出到哪去）
- 与其他模块的调用关系
- 疑似技术债清单（命名混乱、重复逻辑、硬编码配置等）
# 输出格式
- 注释以「// 【补注】」开头，便于后续人工评审时定位
- 架构说明使用 Markdown
- 不确定的内容必须标注[待人工确认]，禁止编造
# 代码如下
<在此粘贴代码>两个关键设计：一是「区分事实与推测」，这是风险控制的核心，避免AI的想象被当成真相沉淀进文档；二是「补注」标记，让评审人员能一眼找到AI新增的内容。
前后对比：一个月后发生了什么
效率层面。 估算过，纯人工梳理八个模块大约需要两个资深工程师一个多月；AI初稿加人工评审，实际花了两个工程师约一周。这不是“AI替代人”，而是把人的时间从“打字写文档”转移到了“判断对错”——后者才是真正需要经验的部分。
协作层面。 之前新同事问问题，只能去堵那位即将离职的老员工；现在模块架构说明就在仓库里，新人 onboarding 时间从原来的“一个月勉强能改小需求”缩短到“一周可以独立处理常规迭代”。交接风险从“系统能不能维护”变成了“文档哪一节需要再补充”。
风险控制层面。 最直观的收益出现在一次线上排查中：某个下游服务报错，以前需要翻代码加问人，这次值班同学直接按架构说明里的调用关系定位到问题模块，处理时间明显缩短。此外，[待人工确认] 标记帮我们在评审阶段揪出了十几处AI理解偏差，也顺带暴露了几段连老员工都说不清来由的历史代码——这些被列入了重构候选清单。
成本层面。 全程消耗的 API 费用折算下来，远低于两个人月的工程师工时（具体模型价格以官网价格页为准，不同模型的成本差异较大，长上下文模型按 token 计费，建议先用一个小模块试算）。我们通过 API 调用模型而非网页版，方便纳入统一的用量监控和预算管理。
几条给管理者的建议
- AI产出必须走人工评审，且评审人要熟悉业务，否则文档的可信度为零，比没有文档更危险。
- 不要追求一次性补全所有代码，按风险排序，从最容易出事的模块开始。
- 把文档放进代码仓库和 review 流程，让它成为工程规范的一部分，而不是躺在某个网盘里的“最终版v3_改.docx”。
- 统一通过 API 管理调用，便于控制预算、审计用量，也方便后续接入更多自动化环节。
老系统不可怕，可怕的是知识只活在个别人的脑子里。AI不能替你理解业务，但它能把你团队的理解成本降一个数量级——这件事，值得你花一周时间试一次。
如果你想开始实践，可以先注册一个 API 账号，从小模块做起：https://api.thistoken.ai/register
---
本文的示例只需一个 API Key 就能复现：在 https://api.thistoken.ai/register 注册即用。