接手遗留项目或 review 他人代码时，快速理解逻辑比重写更费时间。AI 在这一环节的实际价值不是"代替你思考"，而是"帮你建立地图"——快速理清调用链、业务规则和潜在坑点。
8.5.1 用 AI 做代码考古
适用场景：面对无注释的老代码、复杂的正则表达式、或嵌套过深的回调地狱。
有效提问模板：
请解释这段代码的执行流程，重点关注：
1. 输入输出是什么
2. 第X行的条件判断目的是什么
3. 是否存在边界情况未处理
4. 用 Mermaid 语法画出流程图
[粘贴代码]实用技巧：
- 分段投喂：超过 100 行的函数拆成逻辑块询问，避免 AI 漏掉细节
- 追问机制：当 AI 说"这里做了校验"，继续问"校验失败会怎样？有返回错误码吗？"
- 对比验证：让 AI 解释后，用它的解释去反推代码，看是否有遗漏分支
8.5.2 从代码到文档的真实 workflow
不要指望一次性生成完美文档，采用"草稿-校对-固化"三步：
第一步：生成注释草稿
为以下 Python 函数生成 Google Style 的 docstring，要求：
- 参数类型与实际代码一致
- 包含至少一个使用示例（doctest 格式）
- 标注作者标记为 TODO（提醒我后续补全）
代码：[...]第二步：人工校对重点
- 检查 AI 是否把
Optional[str]错写成str - 确认异常抛出列表是否完整（AI 常漏掉隐式抛出的异常）
- 把"作者：AI Assistant"改成实际开发者
第三步：固化到代码库
使用工具自动同步：
- Python: 用
mkdocstrings或sphinx-autodoc从注释生成 API 文档 - JavaScript: 结合
JSDoc和TypeDoc生成类型文档 - 通用方案：配置 Git Hook，提交前用脚本检查文档与函数签名是否匹配
8.5.3 架构文档的生成策略
对于模块级说明，不要直接扔给 AI 几千行代码。先手动梳理目录结构，再让 AI 辅助填充：
- 人写骨架：在
docs/arch.md中写好"用户模块负责认证，包含三个核心类..." - AI 填血肉：针对每个类请求"请详细说明 UserService 的依赖关系，并列出所有公开方法的作用"
- 交叉验证：让 AI 根据生成的文档描述，反推代码结构，检查是否有未覆盖的新增方法
8.5.4 避坑指南
文档过时问题：AI 生成的注释不会随代码变更自动更新。建议：
- 在 Code Review checklist 中加一条："如果修改了函数逻辑，是否同步更新了 AI 生成的注释？"
- 不要用 AI 生成的方法体注释（如
// 这里加1），只生成接口级文档
敏感信息泄露：向云端 AI 解释代码前，脱敏处理：
# 原始代码
api_key = "sk-live-123456"
# 粘贴给 AI 前改为
api_key = "YOUR_API_KEY_HERE" # 敏感信息已脱敏别解释显而易见的代码：如果 i++ 也要写三行注释，反而增加噪音。让 AI 专注解释业务逻辑（如"为什么这里要减去 86400 秒"），而非语法。
8.5.5 实战示例
场景：收到一段遗留的 SQL 优化代码，需要补充文档。
操作过程：
- 先问："这段 SQL 的子查询在解决什么业务问题？"
- 确认理解后，请求："为这段 SQL 生成注释，说明每个索引提示（force index）的原因"
- 最后生成："编写 Markdown 表格，列出涉及的表、字段含义和关联关系"
产出物：
- 代码内联注释（说明优化原因）
docs/database/order_query.md（包含执行计划说明）- 团队知识库条目："历史订单查询优化方案"
关键认知：AI 生成的文档是起点而非终点。把它当作一个"永远耐心的初级同事"——能快速帮你整理思路，但最终的准确性和维护责任仍在开发者身上。