接手历史遗留项目，几乎是每个服务端开发职业生涯里躲不开的“历劫”。上个月，因为业务线整合，我被派去接手一个 2016 年立项的营销活动系统。
第一天拉下代码，真的倒吸一口凉气：整个核心链路的代码超过 5 万行，而且经历过四拨团队转手。最致命的是——没有一份准确的文档。需求散落在各类飞书文档、微信聊天记录，以及充满玄学的代码注释里。新渠道需要接入，前端找我要最新的 API 文档，我看着那个连 Swagger 都没集成的古董 Spring 项目，陷入了沉思。
人肉梳理这些逻辑显然不现实。为了不让项目在交接期直接崩塌，我决定让大模型来做“逆向工程”——直接从烂代码和散落的文档中，倒推出一套标准化的 OpenAPI 规范文档。测试环境放在了一个域名为 ouai.me 的多模型调用站点，方便把同一套“屎山”代码同时喂给几个模型做对比。几轮下来，Claude Opus 4.8 在处理这种长文本交叉理解和复杂业务逻辑抽离上，表现尤其出彩。
今天就来复盘一下，如何用 AI 从一片混沌中重构出清晰的技术文档，以及这套工作流中需要避开的坑。
一、为什么传统的大模型文档生成容易翻车？
最初的想法很简单：把核心 Controller 和 Service 类的代码复制给模型，让它“生成接口文档”就行了。但实际操作下来，直接这么做的结果通常是——看起来很像样，但完全不能用。
直接生成文档主要面临三个问题：
- 隐式依赖丢失：老旧代码里，很多参数校验和默认值赋值根本不在接口层，而是深深埋在某个 Utils 类的静态方法里，或者通过拦截器隐式处理掉了。
- “废弃字段”的干扰：随着业务迭代，不少字段已不再使用，但为了向后兼容，代码里依然保留着接收逻辑。模型如果不做深度理解，会将这些垃圾字段全部写进文档。
- 上下文窗口迷失：梳理一整个下单流程，涉及的代码文件可能多达十几个。早期模型处理长上下文时，常会“忘记”开头，或者把两个无关的实体强行缝合。
这就是为什么最终把主力模型锁定为 Claude Opus 4.8。它的长上下文保持能力极强，在指令遵循方面有着近乎强迫症的严谨。
二、基于 Claude Opus 4.8 的文档逆向工作流
为了保证输出文档的可用性，放弃了“一步到位”的幻想，将整个拆解为三个结构化阶段。
阶段一：逻辑剥离，生成纯粹的业务骨架
第一步，不是让它生成 JSON 格式接口文档，而是让它先看懂业务。把 Controller、主要 Service 实现类以及相关数据实体类发给 Claude，要求输出业务逻辑流。
Prompt 示例：
你现在是一位资深的 Ja va 架构师。我需要你阅读以下这段历史遗留的营销活动处理代码。
【任务目标】
请不要生成代码或接口文档。你需要通读逻辑，帮我提取以下信息：
1. 当前接口接收了哪些核心入参（请剔除明显未使用或标记为 @Deprecated 的字段）？
2. 梳理业务校验规则：有哪些必填项？如果参数为空，代码内部是如何处理的（是否有默认值）？
3. 列出接口的各种返回状态及其对应的业务含义（不要只写 HTTP 状态码，要找出业务 Code）。
【输出格式】
使用清晰的 Markdown 列表输出。遇到模糊的逻辑，请用⚠️标记，不要自行脑补。在这个阶段，Claude Opus 4.8 展现出了极强的代码审查能力。它甚至帮我找出了一个深藏在 if-else 嵌套中的逻辑漏洞：“⚠️ 注意：当渠道号为 'WX_MINI' 时，无论是否传入 userId，系统都会赋予一个默认的游客ID，这可能是一个历史妥协逻辑。”
阶段二：多源数据交叉验证
老代码最大的问题是代码与实际需求脱节。有些逻辑可能是当年的 Bug，有些则是特事特办的硬编码。
这时，我会找出现存的零碎文档（如老旧的 PRD 截图 OCR 文字、会议纪要），连同第一步生成的业务逻辑流，一起发给 Claude 进行“对账”。
Prompt 示例：
【输入 A】：这是从老代码中逆向提取的实际业务逻辑梳理。
【输入 B】：这是 2021 年的一份残缺的产品需求文档。
【任务】
请作为系统分析师，对这两个输入进行交叉比对：
1. 找出代码实现与文档描述冲突的地方。
2. 找出代码中存在，但文档中完全没有提及的隐藏参数。
3. 输出一份《差异分析报告》，帮助我确认哪些是需要和业务方确认的历史包袱。这一步简直是技术债清理神器。Claude 帮我揪出了好几个前端早就废弃不传，但后端仍然在苦苦校验并查询数据库的参数。拿着这份差异报告，直接去找业务方对齐，大大缩短了扯皮的时间。
阶段三：输出标准化 OpenAPI (Swagger) 规范
业务逻辑理清了，废弃字段剔除了，最后一步才是生成可交付前端的文档。这里强制要求 Claude 按照 OpenAPI 3.0 规范输出 YAML 或 JSON。
Prompt 示例：
基于我们上一轮确认过的最终业务逻辑，请为该接口生成符合 OpenAPI 3.0 规范的 YAML 格式文档。
【强制约束】
1. 必须包含完整的 requestBody 和 responses 定义。
2. 每个字段必须包含描述（description）、类型（type）、是否必填（required）。
3. 对于枚举字段，必须在 description 中列出所有可能的枚举值及其含义（如 status: 0-未开始，1-进行中）。
4. 必须提供一个 200 成功响应的完整示例（example），请使用符合真实业务场景的测试数据。
5. 请直接输出 YAML 代码块，不要有任何多余的解释说明。出来的结果令人极度舒适。把这坨 YAML 复制到 Swagger Editor 里，稍微调整一下缩进，一份精美且准确的接口文档就诞生了。
三、不可逾越的安全与脱敏红线
尽管 AI 在梳理历史代码上效率惊人，但在处理公司真实工程时，脱敏是任何时候都不能马虎的红线。将代码复制给 Claude 之前，有一套严格的“洗稿”流程：
- 剔除所有凭证信息：检查代码中是否硬编码了数据库 IP 账号密码、第三方的 AppKey / AppSecret，统一替换为
[DB_URL_REMOVED]这样的占位符。 - 清洗真实测试数据：很多老代码注释里会带着当年出 Bug 时的真实用户手机号、订单号。必须用正则表达式全部清空或替换为
13800000000。 - 模糊商业敏感逻辑：如果某个方法里包含了公司核心的推荐权重算法或高频交易策略，将那部分计算逻辑清空，只保留方法的签名和出入参类型：“这里省略核心算价逻辑，返回一个计算好的 BigDecimal”。只需要 AI 梳理接口结构，不需要它知道商业机密。
四、写在最后
用 Claude Opus 4.8 梳理这套老系统，大概花了三天时间。如果纯靠人工，不仅过程极其枯燥，还非常容易因为脑力枯竭而漏掉关键的防御性判断。
最大的体会是：不要让大模型直接给你最终答案，而是把它当成一个不知疲倦的代码审查员和业务分析师。通过“先解析逻辑 -> 交叉核对需求 -> 最后格式化文档”的防御性工作流，不仅得到了一份靠谱的 API 文档，更重要的是，借由 AI 的视角，完成了一次对系统技术债的深度盘点。
大模型无法替我们承担系统线上运行的责任，但如果能克制地、工程化地使用它，它绝对是对抗那些“祖传屎山”最锋利的武器。