ARTICLE · 1197193
没文档老项目,用 AI Agent 两周接手:可复制 SOP
两周前，我接手了一个 8 年前的老项目。
没有文档、没有注释、没有交接人，只有一个压缩包和一句「应该还能跑」。换作以前，我会先骂三天，再花两周盲人摸象。但这次，我拉着 AI Agent 一起干，10 个工作日把代码结构、改动影响面、回归用例、交接文档全整理了出来。
这篇文章不是炫技，是一份 SOP。你照着做，下次遇到同样的「代码废墟」，可以少走 80% 的弯路。
Step 1：30 分钟，用 AI 画出「项目地图」
别一上来就读代码。先让 AI 从目录结构、配置文件、入口文件 three 个维度扫描，给你一张「地图」。
我用的 prompt 模板：
「你是一位资深架构师。请分析下面的项目目录结构和关键配置文件，用 300 字以内总结：1）这是什么类型的项目；2）主要模块有哪些；3）入口文件可能是哪些；4）最可能藏坑的 3 个地方。请用中文回答。」
把压缩包里的 package.json / pom.xml / requirements.txt 和目录树贴进去，AI 基本能猜个八九不离十。关键动作：让 AI 输出一份「模块关系表」，你把它贴到笔记里，后面每一步都回头查。
Step 2：让 AI 当「代码导游」，生成入口清单
老项目最痛苦的不是代码多，而是不知道从哪里开始读。
我会把项目按「用户操作 → 接口 → 服务 → 数据层」拆成一条链路，然后让 AI 逐个解释：
「请阅读 [文件名] 这个文件，按『这个文件做了什么 → 它调用了谁 → 它被谁调用』三段式解释。如果里面有你不确定的地方，请明确标注『不确定』。」
这里有个技巧：一次只给 AI 一个文件。别一次性塞整个项目，容易超长上下文、容易幻觉。宁可慢，不要错。
Step 3：画一张「改动影响面」图
老项目不敢改，是因为不知道改一行会炸多少地方。我的经验是：改之前先让 AI 做影响分析。
把你计划改动的函数/表名告诉 AI，让它反向搜索调用链：
「请在整个项目中搜索 [函数名/表名] 的所有调用位置，列出：1）直接调用者；2）间接调用链（最多 3 层）；3）可能受影响的测试文件；4）改动时需要重点回归的 3 个场景。」
把结果整理成一张影响面表格，改代码前先对照它做 checklist。这一步能帮你避开 90% 的「改一处、崩十处」。
Step 4：用 AI 生成回归测试用例
老项目通常测试残缺，但你不能没有测试就动手。
我的做法是：先让 AI 读你要改的模块，然后让它基于现有代码补测试：
「请为 [函数名] 生成单元测试用例，覆盖正常路径、边界条件和异常路径。测试框架使用 [Jest/PyTest/JUnit 等]。请先解释这个函数的输入输出，再给出完整可运行的测试代码。」
AI 写的测试不一定能直接跑，但骨架和边界条件基本靠谱。你人工修一遍，比从零写快得多。
Step 5：边做边写「给下一个人」的交接文档
老项目最大的坑，是这次你踩的坑，下次还有人踩。
所以我从 Day 1 就让 AI 帮我维护一份「项目笔记」：
每天结束时，把当天搞懂的模块、踩的坑、TODO 丢给 AI； 让 AI 按「背景 → 问题 → 结论 → 待办」整理成结构化文档； 两周后，这份笔记就是项目的「复活说明书」。
可直接复制的 5 步清单
✅ 接手老项目 SOP（建议收藏）
- 项目地图：
用目录 + 配置文件 30 分钟定位项目类型与模块。 - 入口清单：
沿「用户操作 → 接口 → 服务 → 数据」链路逐个读文件。 - 影响面图：
改动前先让 AI 反向搜索调用链，列出回归重点。 - 回归测试：
让 AI 补写单元测试骨架，人工修一遍再跑。 - 交接文档：
每天把新认知丢给 AI，让它整理成结构化笔记。
3 个不要踩的坑
1. 别一次性把整个项目丢给 AI。超长上下文会让 AI 漏细节、编结论。分文件、分模块问。
2. 别完全相信 AI 说的「这里没问题」。AI 是辅助，最终代码责任在你。关键改动一定要自己跑一遍。
3. 别只顾着改，不补文档。老项目的悲剧是：你花了两周搞懂，下一任又花两周。边做边写，是最大的积德。
最后
AI 不会让老项目自动变干净，但它能帮你把『无从下手』变成『一步一步有地图』。
如果你最近也在啃一个没文档的项目，先把这篇收藏，明天上班照着 Step 1 做 30 分钟。你会回来感谢我的。
觉得有用？点个「收藏」，下次接手老项目时不慌。
