用 AI Agent 逆向 5000 个代码文件：从遗留系统到需求规格说明书的全过程

用 AI Agent 逆向 5000 个代码文件：从遗留系统到需求规格说明书的全过程

逆向工程实践 · AI Agent · 2026-08

一套运行多年的企业级软件，文档散落、人员更迭、业务逻辑锁在代码里。能不能让 AI 直接读代码，逆推出一份完整的需求文档？我们用一个真实项目验证了这件事。

接手一个没有文档的老系统是很多技术团队的噩梦。业务逻辑全在代码里，新人上手靠口口相传，重构和迁移更是无从下手。这次我们尝试让 AI Agent 直接扫描代码目录，自动完成从代码结构分析到需求文档撰写的全过程。本文记录完整的方法论、踩过的坑和最终效果。

目录

1. 问题：当业务逻辑只存在于代码中

企业软件有一个普遍困境：系统上线运行多年，经历了多轮迭代和人员变动，最初的需求文档早已过时甚至丢失。真正的"需求"散落在三个地方——

• 代码里：Controller 名称暗示功能点，Service 层藏着业务规则，Entity 字段定义了数据模型；
• 数据库里：表结构、字段约束、外键关系是数据模型的最终真相；
• 人脑里：老员工知道为什么这么设计、哪些字段已经废弃、哪些流程有历史包袱。

传统做法是组织人力逐模块阅读代码、访谈关键人员、手工整理文档。一个中等规模的系统，这个过程通常需要数周甚至数月，而且整理出来的文档在完成的那一刻就开始过时。

我们面对的是一套典型的行业管理软件——C# ASP.NET MVC 架构，17 个项目，5000 多个源文件，涵盖十几个业务领域。它有三个客户变体版本，代码中通过命名前缀和独立模块区分。目标很明确：在不依赖原开发团队的情况下，仅从代码出发，逆推出一份按领域分类的完整需求规格说明书。

核心挑战

不是"读不懂代码"，而是代码量太大、模块太多。人工逐个文件阅读效率极低，且容易遗漏跨模块的业务关联。需要一种结构化的方法，让 AI 能够系统性地扫描、归类和提炼，而不是泛泛地"看一眼代码就开始写"。

2. 思路：AI 逆向需求的三层映射模型

在动手之前，我们先建立了一个核心认知：MVC 架构本身就是一座从代码通往需求的桥梁。在典型的 ASP.NET MVC 项目中，代码结构与业务需求之间存在三层可机械提取的映射关系：

这三层不是孤立的。Controller 名称引用 Entity，Entity 之间通过导航属性关联，Areas 把相关 Controller 组织在一起。三者交叉验证，就能还原出"谁在什么模块里对什么数据做了什么操作"——这正是需求规格说明书的核心内容。

逆向分析流水线

基于这个模型，我们设计了一条清晰的处理流水线：

📁 目录扫描 → 📊 结构提取 → 🔍 领域归类 → 🤖 深度阅读 → 📝 文档生成
递归列出源文件 Areas/Controller/Entity 按业务语义分组 关键实体与流程 按领域撰写SRS

3. 实战：五步完成代码到文档

第一步：直接访问本地文件系统

最初的顾虑是文件上传限制——如果一个个文件上传，5000 个文件根本不现实。但 Coze Agent 的桌面端能力可以直接访问本地文件系统，通过授权后就能用命令行递归扫描目录，无需上传任何文件。

申请目录权限后，Agent 获得了"始终允许"的授权，后续所有读取操作都无需重复确认。

⚠️ 环境适配：Windows vs Linux 命令

用户本地电脑是 Windows 环境，第一次尝试用 find、ls -R、head 等 Linux 命令全部失败——要么被安全策略拦截，要么 PowerShell 不识别。最终统一改用 PowerShell 原生命令 Get-ChildItem，问题解决。

关键扫描命令（已过滤掉 bin/obj/packages 等编译产物目录）：

# 递归列出所有 C# 源文件
Get-ChildItem –Path 'D:\\Project\\CodeRoot' –Recurse –File `
–Include *.cs,*.cshtml,*.csproj,*.sln |
Where-Object { $_.FullName -notmatch '\\\\(bin|obj|packages)\\\\' } |
ForEach-Object { $_.FullName } | Sort-Object

第二步：提取三层结构

三条命令分别提取目录结构、Controller 清单和 Entity 清单：

这一步的产出是三份结构化清单，不需要 AI "理解"代码，只需要机械提取文件名和目录结构。但这三份清单构成了后续所有分析的骨架。

第三步：按业务语义归类领域

拿到 Controller 和 Entity 清单后，通过命名模式识别业务领域。例如：

DeviceInfo → 设备管理 Parts* → 备件管理
Mrp* → 物料/物资管理 Rep* → 船舶修理
Budg* → 预算管理 Safe* → 安全管理
Supplier* → 供应商管理 PmsDictionay → 系统字典
Book* → 台账/手册管理 wf* → 工作流引擎

同时发现了重要线索：很多 Controller 带有 HKMW_ 前缀，而代码库中存在三个解决方案文件（面向不同客户），说明这是一个多租户/多客户变体的系统。这些变体差异必须在需求文档中明确标注。

第四步：深度阅读关键代码

清单和归类解决了"有什么"的问题，但需求文档还需要回答"怎么运作"。我们选择了每个领域最核心的 Entity 文件进行精读：

• 设备工作项目（device_job）——揭示了基于计数器的保养计划触发机制；
• 工单（work_card）——揭示了工单从创建、审批到完工的完整状态机；
• 物料申请（mrp_apply）——揭示了申请→询价→订单→入库的采购链路；
• 备件库存（parts_material_info/stock/in_out）——揭示了备件台账和出入库流水。

读取实体类的属性定义和 EF Mapping 配置，可以精确到字段级别——字段名、类型、是否必填、最大长度、关联关系。这些是需求文档中数据模型章节的直接素材。

✅ 为什么不读所有代码？

5000 个文件全量精读既不现实也不必要。Controller 名称已经覆盖了功能点的"面"，核心 Entity 精读补充了业务规则的"点"，点面结合足以还原需求全貌。Service 层的业务逻辑可以在需要时按需深入，但对需求文档而言，Controller + Entity 的信息密度已经足够高。

第五步：派发子 Agent 并行撰写

结构化分析完成后，进入文档撰写阶段。这一步的工作量大但目标清晰，适合交给子 Agent 后台执行：

sessions_spawn({
agent: "lead",
name: "PMS需求逆推文档",
task: `基于以下代码分析结果，撰写完整的需求规格说明书…
– 15个业务领域的Controller清单
– 核心Entity字段定义
– 业务流程描述
– 多客户变体差异标注
输出：/项目目录/船舶PMS系统逆向需求分析.md`
})

主会话把前三步提取的全部结构化数据（Controller 完整清单、Entity 字段、领域分类）打包传给子 Agent，子 Agent 专注于文档撰写，主会话保持可响应。约 10 分钟后，一份 1600+ 行的需求规格说明书自动生成。

4. 关键技术决策与踩坑记录

决策一：直接读文件 vs 上传文件

决策二：先提取结构再阅读内容

最容易犯的错误是一上来就让 AI “读代码然后告诉我系统是做什么的”。这种方式在小项目上可行，但面对 5000 个文件时，AI 会被海量信息淹没，产出泛泛而谈的概述。

我们的做法是先建立骨架（目录+文件清单），再填充血肉（精读关键文件）。骨架阶段只提取元数据（文件名、路径、目录结构），不读取文件内容，因此速度极快且不消耗大量上下文。拿到骨架后，AI 对系统全貌有了结构化认知，再精读关键文件时就能精准定位、有的放矢。

决策三：用子 Agent 处理重撰写任务

文档撰写是典型的"输入明确、耗时较长、可独立检查"的任务。主会话已经完成了所有分析工作，把结构化结果交给子 Agent 撰写，既避免了主会话上下文耗尽，又能让用户在等待期间继续对话。

踩坑：Windows 路径中的特殊字符

代码目录路径中包含括号 (BS)，在 PowerShell 中如果不用单引号包裹会被解析为表达式。所有涉及路径的命令都必须用单引号包裹：

# 正确：单引号包裹含特殊字符的路径
Get-ChildItem –Path 'D:\\Project\\(BS)CodeRoot' –Recurse

# 错误：括号会被 PowerShell 解析
Get-ChildItem –Path D:\\Project\\(BS)CodeRoot –Recurse

踩坑：高危命令确认机制

递归扫描命令（如 Get-ChildItem -Recurse）会被系统安全策略标记为高危操作，需要用户在卡片上点击确认。虽然已授权目录访问，但递归扫描仍会触发二次确认。在实际操作中提前告知用户"接下来会有确认弹窗"，可以避免流程中断。

5. 产出物与效果评估

最终交付了一份约 84KB、1646 行的需求规格说明书，包含以下章节：

这份文档好在哪里

• 可追溯：每个功能点都标注了对应的 Controller 名称，可以直接回到代码验证；
• 有优先级：P0/P1/P2 三级标注帮助读者快速识别核心功能；
• 标注变体差异：清晰区分了三个客户版本的特有功能；
• 基于实证：所有需求均来自代码中真实存在的类、方法和字段，没有编造。

它的局限

⚠️ 需要人工补充的部分

代码能告诉你"系统做了什么"，但无法完全回答"为什么这么做"。某些业务规则背后的历史原因、废弃功能与在用功能的区分、以及未体现在代码中的业务约束（如行业合规要求的具体条款），仍然需要熟悉业务的人员进行校验和补充。AI 逆向出的需求文档是一个高质量的起点，而不是终点。

6. 方法论总结与适用边界

回顾整个过程，我们提炼出一套可复用的**"代码逆向需求"方法论**：

适用条件

这套方法在以下条件下效果最好：

• 系统采用了规范的架构模式（MVC、MVVM、分层架构等），代码结构本身就有业务语义；
• 命名规范相对统一，文件和类名能够反映业务含义；
• 有数据模型层（ORM Entity、数据库 Schema）可以提供字段级信息；
• 目标是还原"系统做了什么"而非"为什么这么设计"。

反之，如果系统命名混乱（如 Controller1.cs、TempService.cs）、架构不清晰或大量逻辑写在存储过程中，逆向难度会显著增加，需要更多人工介入。

AI 不会替代你理解业务，但它可以把散落在 5000 个文件中的业务逻辑系统性地打捞出来，整理成一个可以审阅、校验和迭代的文档。从"代码即文档"到"代码生成文档"，这中间的距离，就是 AI Agent 的价值。