实战：用 Agent 快速读懂并上手陌生遗留项目
系列入口：如何使用 Agent。M9 第 2 篇。
一、遗留项目为什么难上手
典型的遗留项目有几座大山：文档缺失或过时、技术栈老旧、命名和黑话自成体系、隐式约定只活在老员工脑子里、而且"能跑就别动"的恐惧笼罩着每个人。 新人往往读了一周代码，仍说不清一个请求是怎么流转的。
Agent 在这件事上价值极大——它不怕枯燥、能快速通读大量代码、还能把结构讲成人话。但要注意：在它不熟悉的代码上，同样可能自信臆测，所以"理解"必须靠运行和测试验证，不能只读它的讲解。
二、第一步：摸清项目骨架
先让 Agent 建立全局地图，而不是一头扎进某个文件。
让它调研并回答：这是什么技术栈、用什么框架和版本、代码怎么分层、入口在哪、如何本地构建和启动、有哪些配置和外部依赖（数据库、消息队列、第三方服务）、测试怎么跑。 让它产出一份"项目导览"，标注关键目录的职责。
这一步你要核查，因为启动方式和依赖最容易被它想当然。方法是亲自按它说的步骤实际跑一次：能不能构建、能不能启动、测试能不能运行。跑不起来也别慌——让 Agent 帮你读报错、补依赖，这个"把项目跑起来"的过程本身就是最有效的第一堂课。能在本地跑起来，你才真正拥有了安全理解和尝试的立足点。
三、第二步：顺一条主链路深入
有了地图，不要平铺地读所有模块，而要挑一条最核心的业务链路，从头跟到尾。
比如一个下单请求：从 Controller 收到、经过哪些 Service、数据怎么落库、调了哪些外部接口、异常如何处理。让 Agent 边带你读边解释每个环节的职责、数据如何变化、有哪些分支。遇到看不懂的命名、缩写、"魔法值"和黑话，直接问它"这个术语/这个字段在这里是什么意思、在哪定义、还有谁用"，让它指回真实代码。
这一步的高价值产出，是一张你自己的主链路图和术语表——把隐式知识显式写下来。这些笔记既是你理解的成果，也可以沉淀成项目文档或 AGENTS.md，惠及后来者。理解一个系统最好的方式，是能把一条真实链路讲清楚。
四、第三步：用特征测试验证理解
只读不验，理解很可能是"自以为懂"。在遗留项目上尤其如此——代码可能有大量没写在表面的副作用和历史包袱。
用 Agent 重构里讲的特征测试在这里正合适：针对现状写测试，记录"当前实际行为是什么"，而不是"我以为应该是什么"。让 Agent 帮你为关键函数补一批这样的测试，覆盖正常、边界和异常输入；跑通后，这些测试就成了你理解的固化，也是日后改动的安全网。
当你的理解与代码实际行为冲突时——比如你以为某分支会执行、测试却显示不会——以代码和测试为准并追问原因，这往往正是隐式约定或历史 bug 的所在。特征测试把"读懂"从主观感受变成可验证的事实。
五、第四步：做第一个安全改动
理解被验证后，再做第一个真实改动，原则是小、清晰、可回退。
选一个范围明确的小需求或修复，建独立分支，让 Agent 在你已梳理的链路和已有的特征测试保护下动手；改完跑相关测试、读 diff 确认只动了该动的地方，再按 验收流程核对。第一个改动的目的不只是交付，更是验证你对系统的理解和安全网是否可靠——如果改动后行为变化都在预期、测试如实反映，说明你已经真正"上手"了。
切忌在尚未建立理解和测试前，就听信"这里可以顺手优化一下"而对核心逻辑大动——遗留系统最怕的就是这种满怀信心的无保护改动。
六、建立你自己的"提问清单"
上手期间，向 Agent 提问的质量直接决定理解的深度。与其泛泛地问"这个函数干嘛的"，不如准备一组能逼出深层信息的固定问题。
几个高价值问法："这个数据从哪来、又流到哪去？"——顺着数据流比顺着控制流更容易抓住业务本质；"这个分支/这个错误处理什么时候会真的触发？"——很多代码是防御性的死分支，弄清它才能区分主路径和边角；"改这里会影响谁？请列出所有调用方和依赖"——为将来改动建立影响面意识，且要让它给出可核查的位置；"这个命名/常量/配置的业务含义是什么？"——把代码符号翻译回业务语言。
更进阶的问法是让它对照解释："这个模块和那个看起来相似的模块有什么区别、为什么不能合并？"这类问题能逼出隐含的设计意图。记住，Agent 的回答仍是待验证的假设，最好的用法是把它当一个不知疲倦、可反复追问的向导，再用代码运行和特征测试去证实它的指引。带着问题清单探索，比漫无目的地通读效率高得多。
七、如何防住 Agent 的臆测
在陌生代码上，Agent 可能把"常见做法"误当成"这个项目的做法"。几道防线：
- 关键论断都让它给出文件与行号，你抽样回源确认。
- 区分它"在代码里确认的"与"推测的"，推测一律标注。
- 优先信运行结果和特征测试，而非它的口头解释。
- 对"这代码很奇怪/应该是 bug"的判断保持谨慎，先弄清历史背景再下结论。
七、常见问题
Q：项目太老、本地根本起不来怎么办？ 这往往是第一道难关也是最大收获。让 Agent 协助分析缺失依赖、版本冲突、环境差异；实在起不来，可先用特征测试和静态分析局部理解关键模块，但改动要更保守。
Q：文档和代码冲突，信哪个？ 遗留项目中文档常常过时，应以能运行的代码和测试为准，同时把确认后的事实更新进文档，消除下一个人的困惑。
Q：多久才算"上手"？ 不必等"全部读懂"——那不现实。能跑起来、能讲清一条主链路、有特征测试保护、并能安全完成一个小改动，就算具备了在该项目上工作的基本能力，其余在实战中持续扩展。
Q：要不要先大重构再开发？ 一般不要。遗留项目应"随到随改"，借每次真实任务局部改善，缺乏全局测试时的一次性大重构风险极高。
八、从"能上手"到"持续精通"
完成第一个安全改动只代表入门，遗留项目的精通是在后续一次次真实任务中扩展出来的，有方法可以让这个过程更系统。
以任务为圆心扩展：不必刻意通读全库，而是每接一个需求，就把该需求涉及的相邻模块彻底弄懂、补特征测试和笔记。几个月下来，覆盖的都是真实高频区域，比预先通读高效。维护一份"已知未知"清单：明确记下哪些模块、哪些行为还没搞懂，而不是假装全懂；这样遇到相关问题时知道该优先查什么，也能在有闲时定点攻坚。
持续回写文档：每弄清一处黑话或隐式约定，就更新进术语表和项目地图，让团队共享，而不是重复消耗。谨慎对待重构冲动：理解越深越容易看到"烂代码"，但应坚持随真实任务局部改善、在测试保护下进行，而非全局性地推倒重来。这样，精通不是某个"我终于全懂了"的瞬间，而是一张随实战不断扩大、且每寸都被测试和事实验证过的认知地图。
九、一个典型的一周上手节奏
把方法落到时间上，更便于安排。下面是一个可参考的一周节奏。
第 1 天，跑起来：让 Agent 帮你摸清技术栈、依赖和启动方式，目标是当天把项目在本地构建、启动成功，并记录所有踩的环境坑。第 2–3 天，读主链路：选一条最核心的业务请求，让 Agent 带你从入口跟到落库，边读边画链路图、建术语表，遇到黑话立即回源确认。
第 4 天，写特征测试：给链路中的关键函数补记录现状的测试，跑通后你的理解第一次被客观验证；对不上预期处重点追问。第 5 天，做小改动：选一个小需求在独立分支完成，配测试、读 diff、验收，借此检验安全网和理解是否可靠。这个节奏刻意"先环境、再理解、后动手"，把最容易卡住的"本地起不来"和最危险的"没懂就改"分别放在最前和最后防护。一周结束时你未必精通，但已具备在该项目上安全工作的立足点，之后再以任务为圆心持续扩展。
十、区分"真懂"和"假懂"
上手中途最危险的是自我感觉良好、实则一知半解。几个客观办法帮你辨别。
能讲给别人听：试着不看笔记把一条链路复述清楚，卡壳处就是没真懂的点。用实验验证：故意改个输入或条件，预测结果再运行，预测对了才算理解。回答"为什么这样设计"：只知道代码做什么是表层，能说出背后的业务或历史原因才是深入，答不出就还停留在假懂。以测试固化：能用特征测试准确描述边界行为，说明理解经住了检验。
十一、向原作者或历史求证
遗留系统里许多"为什么"无法从代码本身读出，善用人和历史记录能省大量猜测。
可让 Agent 帮你检索提交历史、旧 PR、过去的设计文档或工单，还原某段代码的来龙去脉；必要时找原作者（若还在）确认。弄清"这是有意设计还是临时妥协"，直接决定你该不该动它。始终把这些口头/历史信息再用代码事实验证，避免以讹传讹。
十二、把理解沉淀回团队而不只是自己
上手过程中产生的地图、术语表和特征测试，若只留在本地，价值只发挥了一半；把它们回写到项目，才让后来的每个人都站在你的肩膀上。
将确认无误的链路图、术语解释更新进项目文档或 AGENTS.md，特征测试提交入库，并标注哪些"已知未知"仍待攻克。注意只回写经事实验证的内容、不把 Agent 的推测当结论。这样一次新人上手不再只是个人的学习，而成为整个项目知识资产的增量——你把自己走过的弯路标了出来，下个人就不必再走一遍。 当这种"边学边回写"成为习惯，遗留项目最可怕的知识黑箱也会在一次次上手中被逐渐照亮。
Q：项目里没人能回答历史问题怎么办？ 那就以代码、提交记录和可运行行为为最高依据，把无法确认的意图明确标为"未知"，不强行解释；同时在你改动处补测试和注释，让这段历史从你这里重新变得清晰可控。
十三、检查清单
- 已摸清技术栈、目录、启动方式并实际运行成功。
- 已梳理至少一条核心业务链路，形成链路图与术语表。
- 关键模块有特征测试记录现状，理解经运行验证。
- 第一个改动小而可回退，有测试与验收保护。
- 关键论断均回源确认，推测已标注，未做无保护大改。
总结
用 Agent 上手陌生遗留项目，顺序是"先跑起来、再读主线、用测试验证、最后小改"：让它先帮你摸清技术栈和启动方式并亲自运行，然后挑一条核心业务链路深入、把黑话和隐式约定整理成自己的地图与术语表，用特征测试把"自以为懂"变成可验证事实，再在安全网保护下完成第一个可回退的小改动；对它在不熟悉代码上的自信推断坚持回源核查，你就能把原本要几周的摸索压缩到几天，并且从一开始就站在安全的地基上。