接手陌生代码库怎么用 AI 快速上手：四步梳理法与验证清单

云上的幻象2026-10-188 分钟阅读2,882 字10

100%

接手陌生代码库时，先让 AI 把「入口在哪、请求怎么走、改动会碰到谁」三件事问出来并自己动手验证一遍，再开始改代码；顺序反了，AI 只会给你一段听起来合理但经不起跑的错误结论。

为什么一上来就问「这个项目是干什么的」没用

新手最常见的做法是打开对话框问一句「这个项目是做什么的」，然后照着答案找文件。这个动作有三个问题：

模型没有仓库上下文时会依据目录名和文件名推测，推测出来的架构经常是「看起来很标准的那一种」；
大仓库一次塞不进上下文，模型只看到局部，会把测试目录、示例代码或历史遗留模块当成现行主逻辑；
结论无法验证。你不知道它说的入口是真实入口，还是恰好排在目录前面的那个文件。

GitHub 工程师在分享如何熟悉新代码库时，给出的第一条建议恰恰相反：先动手探索，从 Good First Issues 这类小任务切入，边看边把 Copilot Chat 开在旁边问。这个顺序的关键在于「先有真实接触点，再要解释」。

四步梳理法

第一步：先要地图，不要要结论

问架构，不问用途。并且强制要求给出证据——文件路径加行号，没有证据的结论一律标为待验证。一份可用的提问模板：

这是本仓库的目录树与入口文件清单。请回答：
1. 程序启动入口是哪个文件，启动后依次加载了哪些模块
2. 模块之间如何依赖，画出调用方向
3. 数据最终落在哪里（数据库 / 文件 / 外部 API）
4. 每一条结论后面附上 文件路径:行号 作为证据
不要推测，找不到就说找不到。

这一步的目标不是「读懂」，而是拿到一张可以自己核实的草图。 Cursor 官方文档在讲陌生代码理解时也强调同一件事：先要整体架构，再下钻到具体任务、测试策略和配置。

第二步：追一条主链路

不要横向铺开读所有模块。挑一条最高频的链路——一个 HTTP 接口、一条命令、一次定时任务——从入口一路追到存储层，并要求输出时序图：

追踪一次 POST /api/orders 请求的完整路径：
经过哪些中间件、做了哪些校验、调用了哪些服务、
最终写进哪张表。用 Mermaid 时序图输出，每个节点标注文件位置。

这一步的价值是建立「改哪里会碰到什么」的直觉。看懂一条链路比泛读十个模块有用得多，检索层面的技巧可以配合代码检索三步法一起用。

第三步：用改动验证理解

这是最容易被跳过、也最不能跳过的一步。挑一处你自认为看懂的地方，做一次最小改动并观察结果：

改一个常量、加一行日志，跑起来看现象是否符合预期；
写一个最小断言，把「我以为的行为」固化成测试；
故意在开发分支里破坏它，观察失败路径。

改对了说明理解成立，改错了说明前两步的结论有偏差，正好回去修正。把这一步交给模型自己做是不行的——模型不知道运行时长什么样，除非你把运行时信息喂给它。

第四步：把结论沉淀成项目上下文文件

验证过的结论要落到文件里，否则下一次开新会话又要重来一遍。写成规则文件供后续会话自动加载：

# 项目上下文
## 架构
- monorepo，三个包：api / web / shared
- api 用 Express + TypeORM，web 用 Next.js
## 常见模式
- 新增接口参考 src/api/routes/users.ts
- 业务逻辑在 service，数据访问在 repository
## 禁区
- src/api/auth/legacy 是遗留鉴权，不要动
- 部分老服务仍是 callback 风格，不要混用 async/await

这个文件有双重作用：既让 AI 下次少走弯路，也是给下一个新人看的文档。具体的组织方式可以参考项目记忆文件指南。

遇到「这段代码为什么这么写」的疑问，先让 AI 查提交历史和 blame 再下判断。看起来别扭的兼容分支，往往是当年修某个线上问题的产物，删掉会立刻回滚那个 bug 。

四类问题该问什么

你想知道的	该这样问	别这样问
结构	列出入口文件与模块依赖，附文件路径	这个项目用了什么架构
流程	追踪一次 X 请求从入口到存储的完整路径	订单模块怎么工作的
影响面	重命名 Customer 会影响哪些文件，逐个列出	改这个类名安全吗
历史原因	查这段代码的提交历史，说明它为什么存在	这段代码能不能删