GenAI for Legacy Codebases

Brief

最近几个月，我们已经看到清晰的证据：使用生成式 AI 来理解遗留代码库，能够显著加速对大型、复杂系统的理解。像 Cursor、Claude Code、Copilot、Windsurf、Aider、Cody、Swimm、Unblocked 以及 PocketFlow-Tutorial-Codebase-Knowledge 这样的工具，可以帮助开发人员挖掘业务规则、总结业务与技术逻辑，并识别系统依赖关系。配合开放的技术框架和直接对大模型进行提示（prompt），这些工具能大幅缩短理解遗留代码库所需的时间。

我们在多个客户项目中的经验表明：借助生成式 AI 来理解遗留系统，现在已经是一个实用的默认选择，而不再只是试验性的做法。前期的环境与数据准备工作量会有所不同，尤其是像 GraphRAG 这类高级方法，其成本通常会随着被分析代码库的规模和复杂度而增长。尽管如此，对生产力的正向影响却是持续而且显著的。生成式 AI 已经成为我们探索和理解遗留系统方式中的一个关键组成部分。

来源：技术雷达

Guide

1. 诉求与意义

从架构视角看，理解遗留代码库通常有几类核心诉求：

1. 业务能力映射：
   • 当前系统是如何实现核心业务流程的？
   • 哪些模块对应哪些领域边界（领域驱动设计中的 $$Bounded\ Context$$）？
   • 有哪些隐性业务规则只存在于代码里而没有文档？
2. 架构结构与依赖图谱：
   • 分层（UI/服务层/领域层/基础设施层）是否清晰？
   • 系统内部、系统间有哪些高耦合依赖？
   • 哪些模块是“关键路径”或“热点服务”，是未来演进和拆分的重点？
3. 质量属性与风险点：
   • 性能瓶颈可能集中在哪些模块（如同步远程调用、复杂循环、IO 密集逻辑等）？
   • 安全、审计、合规逻辑分布位置？
   • 技术债的集中区域（上古框架、过时库、硬编码配置、临时补丁等）？

生成式 AI 为以上问题提供了一个**高效率“放大镜 + 导游”**的组合：

• “放大镜”：细粒度阅读与解释代码、注释、配置、脚本。
• “导游”：根据我们的问题视角（业务/性能/安全/架构），组织和重构信息，形成更贴合架构决策的视图。

2. 工具在分析中的典型用法

原文提到的工具（Cursor、Claude Code、Copilot、Windsurf、Aider、Cody、Swimm、Unblocked、PocketFlow-…）本质上都围绕几个共同能力：

1. 代码语义搜索与问答
   • 按“业务概念”搜索：例如询问“订单取消流程从哪里开始？涉及哪些服务和数据库表？”
   • 按“架构关注点”搜索：“系统中所有调用外部支付网关的代码与配置有哪些？请画出依赖图。”
2. 自动摘要与结构化输出
   • 对一个模块/服务/目录，让模型生成：
     • 功能摘要
     • 输入输出
     • 关键业务规则
     • 主要依赖（服务/库/外部系统）
   • 架构师可以据此快速构建：
     • 业务能力清单
     • 服务拓扑图
     • 数据流图 / 依赖图
3. 跨文件/跨服务的依赖分析
   • 借助工具内置的“项目索引”能力或 GraphRAG，一次性回答：“从 Web 层到数据库，‘用户注册’这条调用链完整路径是什么？”
   • 对微服务或模块化单体，帮助识别：
     • 循环依赖
     • 未经网关直接互调
     • 隐式共享数据库/表
4. 业务规则“挖掘”
   • 传统问题：很多老系统的业务规则只存在于代码条件判断中。
   • 生成式 AI 能把分散在多处的 if/else、校验、状态机逻辑聚合成：
     • “订单状态流转规则一览”
     • “贷款审批的所有规则及其触发条件”
   • 架构层面可以用这些结果去：
     • 反推领域模型
     • 识别跨上下文的“业务泄漏”（某个上下文不该关心的规则却出现在了这里）

3. 与开源框架 & GraphRAG 的结合方式

原文提到 “open frameworks and direct LLM prompting” 和 “GraphRAG”等，更偏工程实践，但对架构也很关键：

1. 直接 Prompt + 编辑器/IDE 插件
   • 适合：
     • 较小代码库
     • 初步摸底、临时问题排查
   • 架构侧用途：
     • 快速查看某个模块的设计意图和实现差异
     • 比对“架构蓝图”与“代码现状”的偏差
2. 自建文档/代码知识库 + RAG（检索增强生成）
   • 将代码、README、API 文档、架构图、接口说明导入向量库：
     • 支持 “在整个系统知识库上提问”
   • 架构侧用途：
     • 做“系统级问答平台”
     • 支持新成员快速理解架构
     • 支撑架构评审、方案论证时的事实核查
3. GraphRAG（图结构 + RAG）在架构场景的好处
   • 不只是“把文档切块”，而是显式建图：
     • 节点：服务、模块、类、数据库表、API、队列等
     • 边：调用关系、依赖关系、数据流向、事件订阅
   • 架构层面可以用来：
     • 自动生成或更新 C4 模型中的 C2/C3 级别图
     • 自动识别“高耦合簇”与“潜在拆分边界”
     • 支持“基于图”的提问，例如：“所有依赖用户服务的下游服务有哪些？影响面如何？”
4. 成本与收益考量（架构视角）
   • 成本随代码规模和复杂度增加：
     • 代码索引与向量化时间
     • 图构建与维护成本
     • 安全与访问控制（避免将敏感代码泄露到第三方）
   • 但收益在架构活动中高度稳定：
     • 需求：系统重构、云迁移、微服务拆分、合规审计、并购系统整合
     • 目标：缩短“理解阶段”的时间，让架构师把时间放在“设计决策”而不是“翻代码”

4. 在架构活动中的典型应用场景

可以在内部分享时用以下几个“故事化场景”来说明：

1. 遗留单体 → 微服务拆分
   • 用 GenAI：
     • 列出业务能力与相应代码位置
     • 找出跨能力的共享数据库表与强耦合模块
   • 产出：
     • 候选领域上下文划分
     • 优先拆分的服务列表
     • 拆分风险（共享事务、跨上下文业务规则）
2. 云迁移或平台迁移（如上云、从自建 ESB 到 API 网关）
   • 用 GenAI：
     • 盘点所有外部系统调用、消息通道、定时任务
     • 分类现有集成模式（同步调用、异步事件、批处理）
   • 产出：
     • 集成点清单
     • 演进式迁移路线（先“包裹”再“替换”）
3. 性能/可靠性治理
   • 用 GenAI 分析：
     • 所有远程调用点、重试机制、降级策略实现
     • 事务边界与锁使用
   • 产出：
     • 容错架构现状图
     • 性能/可靠性改造切入点
4. 合规与安全审计
   • 用 GenAI 搜索与聚合：
     • 密码/秘钥处理逻辑
     • 个人数据处理与脱敏逻辑
     • 审计日志记录位置
   • 产出：
     • 与法规（如 GDPR、数据安全要求）对齐的“现状对照表”
     • 缺口与整改优先级

5. 实施建议

1. 把 “GenAI 辅助理解” 设为默认动作
   • 新接管一个遗留系统时：
     • 第一周就搭建基本的 AI 助手（哪怕只是 IDE 插件 + 项目索引）
   • 把“问 AI”当作与“全文搜索”“读文档”同等优先的手段。
2. 架构师主导问题视角
   • 避免只用来写代码或解释局部函数；
   • 要刻意提出架构级问题，例如：
     • “从架构分层角度总结本项目的结构，并指出不一致之处。”
     • “按领域边界帮我重新分组这些模块，给出分组依据。”
3. 结合人工判断，避免“AI 版本的错觉式架构图”
   • 所有自动生成的：
     • 架构图
     • 依赖总结
     • 业务规则列表
   • 都要通过抽样验证和代码 spot check 来确认准确性，逐步修正。
4. 注意安全与合规
   • 对含敏感代码的项目：
     • 优先选择本地部署或企业版 LLM 方案
     • 在组织层面明确：哪些仓库可以、哪些不可以接入外部云端 AI 工具。