大型代码库的问答与理解
系列入口：如何使用 Agent。进入扩展模块 M12「扩展应用与运维实战」。
一、为什么大库理解是 Agent 的高价值场景
一个有经验的工程师接手陌生系统时，最大的瓶颈不是写代码，而是建立心理模型：这个请求从哪进来、经过哪些模块、数据存到哪、有哪些隐藏约定。在几十万甚至上百万行的库里，靠 grep 和逐个文件阅读，可能几周都摸不清主干。
Agent 恰好擅长在这种规模下工作：它能并行阅读大量文件、沿调用关系顺藤摸瓜、并把分散在各处的信息综合成回答。它把"理解一个系统"的周转时间从"周"压缩到"小时"。但代价是——它可能把没读过的代码也讲得头头是道，因此理解类任务同样需要溯源，不能照单全收。
二、先建代码地图，再提问
直接问"这个系统怎么工作"往往得到泛泛而谈。高效的做法是先让 Agent 产出一张代码地图：顶层目录各自负责什么、核心模块的入口文件、主要的数据流和依赖方向。
可借助 CodeGraph 这类工具（见站内 CodeGraph 代码地图）提供结构化索引，也可以让 Agent 先读 README、构建配置、路由注册、模块清单等"骨架文件"，自己画出地图。有了这张地图，后续所有问题都能定位到具体模块，而不是在整个库里大海捞针。把这张地图作为共享上下文反复使用，比每次重新描述项目高效得多。
三、沿调用链问，而不是搜关键词
新人最容易用的方式是关键词搜索，但一个叫 handle 的函数可能有几十处。Agent 的优势是按语义和调用关系追踪：从一个具体入口（一个 HTTP 路由、一个命令、一个消息消费者）出发，让它"顺着这条链路，列出请求依次经过的函数、每步做了什么数据变换、最终落到哪里"。
这种"链路式提问"得到的是一条可验证的执行路径，而非零散片段。对复杂分支，让它分别说明正常路径和异常路径。一次只追一条主链，比让它一次讲清整个系统更准确，也更容易发现它在哪一步开始臆测。
四、多轮追问逼近真相
理解是逐层深入的，不要指望一问到底。一个有效的追问节奏：
先问主干（链路怎么走），再问细节（这一步为什么这样设计、这个参数什么含义），然后问边界（什么情况下会失败、有哪些并发或权限约束），最后问历史（这块为什么和别处不一样、有没有已知坑）。每一轮让它给出具体文件和行号作为依据。当回答里出现无法定位到代码的"自信陈述"，就是它可能在编造的信号，应让它回原文核对（参见幻觉识别）。
五、让它画图、举反例、当老师
除了文字回答，几个动作能显著加深理解并暴露错误：让它生成架构图/时序图（PlantUML/Mermaid），画图过程会逼它理清关系，你也能一眼看出不合理处；让它举一个具体输入、逐行走一遍，把抽象链路落到可感知的数据上；让它扮演老师向你讲解、并允许你随时打断提问，讲不清的地方往往就是理解（包括它的理解）的盲区。
这些与把 Agent 当私教的方法相通（见用 Agent 学习新技术）。
六、溯源验证：回答必须能落到代码
理解类任务最危险的失败，是它引用了一个根本不存在的函数或 API。验证方法简单但关键：抽查它给出的文件路径、函数名、调用关系是否真实存在且如它所述；对关键结论，点进源码亲自确认；让它在回答中附上代码片段和行号，而不只是结论。
如果某条链路它解释得含糊或前后矛盾，让它重新读取相关文件，而不是接受一个圆滑的答案。信任的建立方式与其他任务一致——可信的回答应该是可追溯的。
七、把理解固化成文档
一次问答的价值会随会话结束而流失。当你确认了一块系统的正确理解后，让 Agent 协助整理成文档：模块职责、入口与主链路、关键约定、坑与边界，回写到项目的架构文档或知识库（方法见补测试与文档）。
这样既沉淀了团队知识，也让下一个接手的人（包括未来的你）不必从零开始。让 Agent 在"读懂"之后顺手"写清"，理解就从一次性消费变成了可复用资产。
八、一个具体的理解过程：从"下单失败"到看懂交易系统
抽象流程之外，走一遍真实感很强的过程，更能体会节奏。
某工程师第一天接手交易系统，接到问题"部分用户下单返回失败"。他没有直接 grep 报错文案，而是先让 Agent 读路由与服务清单，画出一张地图：下单请求经过网关、订单服务、库存、支付四个模块。然后他只追一条主链："从下单接口开始，列出请求经过的函数和每步的状态判断。" Agent 顺链发现订单服务会先调库存预占、再调支付，而支付返回某错误码时会让整单失败。
接着他追问边界："这个错误码什么情况下出现？涉及哪些用户？" Agent 沿支付模块读到，它与某个新接入渠道的超时配置有关，且只命中特定地区用户。整个过程他都让 Agent 附行号，并亲自点开关键的错误码判断确认，没有轻信。半天内，他不仅定位了问题，还借这条链路建立起对交易主干的心理模型。这个例子说明：一次具体的排查，往往就是理解一个系统的最佳入口，而 Agent 让这条"由点到面"的路径走得极快。
九、提问的几种有效模板
把好用的问法固化成可复用模板，能显著提高问答质量。
链路定位："从 X 入口开始，列出请求依次经过的函数、每步的数据变换、最终落到哪个存储，附文件行号。"影响分析："如果我修改这个函数的签名，哪些调用方会受影响？分别在哪？"约定挖掘："这个模块在错误处理/并发/权限上有哪些与别处不同的约定？"反向解释："这段代码为什么要这样写？如果改成直观写法会有什么问题？"
这些模板的共同点，是要求具体、可定位、且常常逼它做因果解释，而不是接受笼统描述。避免"这个系统怎么设计的"这类大而空的问题——问题越聚焦，它越难以含糊带过，你也越容易验证。把你验证有效的问法存进团队的提示词资产，新人就能直接站在好用法的肩膀上。
十、带着"修改目标"去理解，理解最深
纯粹为了"看懂"而阅读，往往浮于表面；最高效的理解方式，常常是带着一个要动手的小改动去读。
当你的目标是"给下单流程加一个字段"或"调整这条规则"，你会被迫真正读懂相关链路的数据结构、校验和落库，而这种理解是带着问题、有落点的。让 Agent 先帮你定位"为了做这个改动，需要读懂哪些代码"，再围绕这个最小集合深入，改完跑测试验证。一个安全的小改动，是把理解从"被动知道"逼成"主动掌握"的最好驱动。 这与遗留项目上手中"先摸骨架、再做首个安全改动"的节奏完全一致——理解和实践本就是一体两面。
十一、把"读不懂"的卡点显性化
理解大库时，有些地方怎么读都觉得别扭，这类卡点往往最有价值，值得显式记录、定向攻克。
当 Agent 的解释和你看到的代码对不上、或某段逻辑完全反直觉，别急着放过——让它重新读原文、列出相关的所有分支和调用，逐步对齐；仍讲不通，就结合 git 历史和测试用例找答案，或请教熟悉的同事。卡点之所以重要，是因为它通常对应着一个隐藏约定或历史包袱，一旦打通，对系统的理解会上一个台阶。把"这里为什么怪"记录下来，正是最值得沉淀的知识。模糊的"大概懂了"会在你动手时还回来，显性卡点并攻克它才是真懂。
十二、理解也要避免"过早下结论"
理解陌生系统时，人很容易在前几屏代码后就形成一个解释、并据此解读后续一切，这种过早结论和幻觉一样危险。
应对方式是主动保留多种可能：让 Agent 在证据不足时给出几个候选解释、各自标注依据强弱，而不是急于锁定一个；随着读到更多代码，再收敛。当新证据与早期解释冲突，要愿意推翻重建，而不是让 Agent 找理由维护旧说法。理解是一个假设逐步被证据修正的过程，保持开放、让代码而不是先入为主来下结论，你建立的心理模型才更贴近系统真实——这和严谨排障的"假设—证伪"是同一种纪律。
十三、和团队共享"理解成果"
个人建立起系统理解后，让它在团队内流动，价值会放大；否则知识仍集中在个别人脑中。
把你确认的代码地图、关键链路、隐藏约定整理进团队知识库，并在相关模块留下指向文档的链接；新人接手时直接从这些成果出发。让 Agent 协助把一次性问答转成可复用的导览。理解一旦沉淀共享，团队的整体上手成本都会下降，也降低了"只有某人懂这块"的单点风险。这正是大库理解从"个人技能"变成"组织能力"的关键一跃，与团队知识沉淀的整体实践一脉相承。
十四、常见问题
Q：要不要给 Agent 整个仓库？ 不必、也常常超出上下文窗口。用代码地图/索引指向相关模块，让它按需读取，比一次性塞入全库更准。
Q：它讲的和实际代码不符怎么办？ 以代码为准，让它回原文重读并解释差异；反复出错的模块，标记为需人工确认。
Q：没有 CodeGraph 这类工具能用吗？ 能。让 Agent 先读目录结构、构建与路由文件自建地图，效果依然显著，只是结构化程度低一些。
Q：理解老系统时还要看 git 历史吗？ 值得。让它结合 commit/PR 历史解释"为什么这样设计"，能发现很多代码本身看不出的背景。
九、检查清单
- 已先建立代码地图/索引作为共享上下文。
- 从具体入口沿调用链追踪，而非关键词海搜。
- 多轮追问主干、细节、边界、历史，并要求行号。
- 已抽查路径与函数真实性、识别编造的 API。
- 确认后的理解已固化为架构文档。
总结
用 Agent 理解大型代码库，关键是"先建地图、顺链追问、溯源验证、固化文档"：让它先产出模块与数据流的代码地图、借助结构化索引定位上下文，再从一个具体入口沿调用链追踪请求、分主干—细节—边界—历史多轮追问，每个结论都要求落到真实文件和行号、并抽查以识破它可能编造的 API，最后把确认无误的理解回写成文档——这样你能用几小时建立起过去要几周的系统心智，同时因为坚持"回答必须可追溯"，而不会被它流畅却失实的解释带偏。