用 AI 快速熟悉陌生代码库

接手一个陌生代码库,是每个开发者都躲不过的劫。尤其是别人留下的、或刚入职的项目——没文档(或有但早过时了),几十上百个目录,几万行代码。你打开编辑器,光看目录结构就头大:这个 core/ 和 engine/ 有什么区别?那个 services/ 里十几个文件谁是入口?一个 API 请求进来,到底走了哪些层?

以前的标准做法是"硬读":挑一个入口文件,顺着调用一层层点下去,边读边在脑子里画依赖图。一个中等规模的后端项目,没有三到五天根本摸不清骨架;碰到 monorepo 或遗留系统,一周起步。这中间你还会反复迷失——读着 A 发现依赖 B,B 又引用 C,等绕回来已经忘了最初在看什么。

AI Agent 把这个时间压缩了一个数量级。不是因为它比你聪明,而是因为它读得快、不累、能系统化扫描,而且不会"读到一半走神"。但前提是:你不能像无头苍蝇一样问它"这个项目怎么样",你得有一套结构化的提问和验证方法。这篇就把我在十几个陌生仓库上反复验证过的一套 onboarding 工作流讲透。

一、第一步:让 Agent 通读,生成架构概览

Onboarding 的第一件事,不是去读某个具体文件,而是先建立全局地图。没有地图,你读的每一个文件都是孤岛。

我对 Agent 的第一条指令,几乎永远是这个:

你是资深架构师。请通读这个仓库,给我一份架构概览,包含:
1. 项目是做什么的(一句话)
2. 顶层目录结构,以及每个目录的职责
3. 主要入口(服务启动、CLI 入口、页面入口分别在哪)
4. 核心模块之间的依赖关系(谁依赖谁,有没有分层)
5. 技术栈和关键依赖
先从 package.json/配置文件/README 看起,再读关键源码验证。
输出要分层,别一上来就贴代码。

为什么这么写?几个要点:明确角色(架构师视角而非程序员),明确产出结构(五点清单,防止它东拉西扯),指明切入路径(从配置文件看起——这是我最常告诉新人的诀窍:配置文件是项目的"目录"),要求分层不要贴代码(概览阶段贴代码就是噪声)。

Agent 会先去读 package.json(看 scripts 和依赖)、tsconfig.json/next.config.ts(看技术栈和路径别名)、prisma/schema.prisma(看数据模型)、目录树,再抽样读几个核心文件验证判断。几分钟内,它会给你一份带目录职责、入口位置、依赖方向的概览。

这里的关键动作是:让它读真实文件,而不是凭目录名猜。 劣质的概览长这样:"services/ 应该是服务层,utils/ 是工具函数"——全是"应该是"。好的概览长这样:"src/services/ 下有 8 个文件,userService.ts 是用户域核心,被 api/users/route.ts 和 api/auth/route.ts 调用,依赖 prisma 和 lib/redis"——有证据。

拿到概览后,我一定会做一件事:挑两个它提到的入口,人工点开验证。这是建立信任的关键。如果它说入口在 src/server.ts,你打开一看确实在那、职责也对,后面你才敢放手让它自己追。如果它错了(比如把测试入口当成了主入口),现在纠偏成本最低。

二、追踪调用链:从入口到落地的完整路径

有了地图,下一个高频需求是追一条具体链路。典型问题:"用户发起一个 POST /api/orders 请求,从进来到订单写进数据库,完整走了哪些代码?"

这种问题靠人追,你得点开路由文件 → 找到 handler → 看 handler 调了哪个 service → service 调了哪个 repository → repository 跑了哪条 SQL。中间还穿插着中间件、鉴权、校验、事务。一个不留神就漏了一层。

交给 Agent:

追踪这个请求的完整处理链路:POST /api/orders
从路由层开始,顺着每一层调用,一直追到数据库写入。
我要的是:每一层在哪个文件哪个函数,做了什么(鉴权?校验?业务逻辑?持久化?),
以及它把控制权交给了谁。最后给一张调用图(文字版即可),
标出跨层的地方和可能有性能问题的地方(比如循环里查库)。

这条指令的精髓:给起点、给终点、给中间要捕获的信息、给额外的分析维度(标出跨层和性能隐患)。Agent 会顺着调用链一路 grep + read,把走过的每一站列出来,顺手指出"这里在 for 循环里查了数据库,N+1"。

一个实战经验:追调用链时,让 Agent 同时画一张"反向依赖图"也很有用——即"这个 service 被谁调用"。改动一个模块前知道它的爆炸半径,往往比读懂它本身更重要。

三、问"某功能怎么实现":定位 + 解释一步到位

第三个典型场景是功能理解:"这个项目的权限控制是怎么实现的?""订阅到期怎么处理?""搜索功能是怎么做的?"

这种问题的特点是:你不知道相关代码散在哪些文件。新手会问"权限在哪",得到一个文件名就满足了;老手要的是定位 + 逻辑解释 + 关键设计意图。

这个项目是怎么做权限控制的?
请:1. 找出所有相关文件(中间件、装饰器、guard、工具函数)
2. 解释整体策略(RBAC?ABAC?硬编码?)
3. 指出权限检查在哪几个入口生效,哪些入口"漏了"权限检查
4. 如果要新增一个角色,该改哪几个地方

第 3 点尤其值钱——"哪些入口漏了权限检查"是 Agent 顺手能给你、但你自己很难系统排查的东西。它能把所有路由 handler 列出来,逐个标注"有 guard / 无 guard",漏网的接口立刻显形。到这里,已经从"读代码"升级到"审计代码"了。

四、识别风险与技术债:让 Agent 当你的审计员

Onboarding 不只是读懂,还要知道哪里有雷。雷往往比正常流程更重要,因为那才是你接手后要还的债。

让 Agent 切换到"审计员"视角扫一遍:

以资深工程师的视角,审计这个仓库,重点指出:
1. 可疑模式:硬编码的密钥/密码、eval、SQL 拼接、未校验的外部输入
2. 复杂度热点:函数过长、嵌套过深、单文件过大的地方(Top 5)
3. 测试缺口:核心业务逻辑里哪些完全没有测试覆盖
4. 技术债信号:大量 TODO/FIXME、已废弃但未删的代码、重复实现
每条给具体文件和行号,以及它为什么是风险。

Agent 会给你一份带证据的清单。这套东西的价值在于系统化——你自己读代码,只会注意到你路过的那几处;Agent 能把全仓扫一遍,把"你不知道你不知道"的问题摆到台面上。

不过有一条铁律:Agent 报告的风险,动手改之前必须人工复核。它有时会把"刻意为之的设计"误判成风险(比如某处看似 SQL 拼接,其实输入是内部生成的、安全的)。复核成本低,误信代价高。

五、给 Agent 好的索引:语义检索 + AST/LSP,让它读得准

前面四步能跑通的前提,是 Agent 找得准。一个残酷的事实:纯靠 grep + 全文读的 Agent,在真实代码库里会大量"读不准"——它会把同名方法当同一个、漏掉动态调用、误判符号归属(这点我们在《代码智能:AST + LLM 的组合》里详细讲过)。

所以想让 onboarding 的结论可靠,得给 Agent 配上结构化索引:

• 语义检索 / 代码库索引:像 Cursor 的 codebase 索引、Claude Code 的 codebase 检索工具,把仓库做成可语义召回的知识库。问"权限相关代码"能召回全,而不是只 grep 到字面含 "permission" 的文件。
• AST / LSP:对"调用点""引用""类型"这类结构问题,用 LSP 的 references/definition 或 TS Compiler API 拿到语义级的真实答案,而不是让 LLM 靠文本猜。

实战中,我会让 Agent 先用语义检索做粗筛,再用 LSP/AST 做精确定位。追调用链时,语义检索帮它快速锁定"订单相关的几个文件",LSP 帮它确认"这个 createOrder 到底被谁真实调用"。前者管广度,后者管精度。没有结构化索引,Agent 给你的概览可能就是"看起来对、实则漏了三条动态调用路径"——而这种漏,正是你后面改代码翻车的根源。

六、局限:超大库、运行时行为、隐式约定——概览必须验证

最后必须说清 AI onboarding 的边界,免得你过度信任翻车。

第一,超大库会超出 Agent 的有效上下文。 几十万行的 monorepo,Agent 没法在一次会话里读全,它会采样——而采样就有偏差。这种情况下要先按子包/子目录拆分,让 Agent 分块出概览,再人工拼装。

第二,Agent 读的是静态代码,看不到运行时行为。 它能告诉你"这里用了 Redis 缓存",但不知道"线上这个 key 的实际命中率、有没有雪崩"。涉及运行时性能、真实流量、数据分布的问题,只能靠监控和日志,Agent 给不了答案。

第三,隐式约定它读不出来。 团队的代码规范、谁负责哪块、为什么当初这么设计(可能是因为三年前踩过一个坑),这些藏在人脑子里和 PR 历史里,不在代码里。Agent 能看到"代码长这样",看不到"为什么长这样"。

所以一条不可妥协的原则:Agent 给的概览是"高质量草稿",不是"已核实的事实"。 每一个你要据此做决策的结论——尤其是动手改代码前——都必须人工抽验。验证的成本,远低于基于错误理解动手后的返工成本。

小结

• 先建地图再读细节:第一条指令永远是让 Agent 通读出架构概览(目录职责/入口/依赖),没有地图,读再多文件也是孤岛。
• 把分析维度写进 prompt:追调用链、问功能时,不止问"怎么实现",还要它标出跨层、漏权限、N+1——把读代码升级成审计代码。
• 风险识别要系统化:让 Agent 带审计员视角全仓扫一遍可疑模式/复杂度/测试缺口,但它报的雷必须人工复核。
• 给 Agent 结构化索引:语义检索管广度、AST/LSP 管精度,纯 grep 的 Agent 在真实代码库里会漏动态调用、误判符号,结论不可信。
• 概览是草稿不是事实:超大库采样偏差、运行时行为、隐式约定都是 Agent 的盲区;动手改之前必须抽验。

AI Agent 把 onboarding 从"读一周"压到"读几小时",靠的不是更聪明,而是读得快、不累、能系统化扫描。但读得快不等于读得准——真正决定 onboarding 质量的,是你提问的结构、给的索引,以及最后那道人工验证的关。