进新代码库以前要一周点目录、两周结对、一个月才能 land 一个非琐碎的 PR。现在有能直读整个仓库的 Agent，同样的”入门”压成专注的一天就够——前提是按对的顺序问对的问题、逐条核验、并把学到的落到自己的文档里。这是任何新加入项目、或几个月后回到老项目的开发者第一天就该跑的仪式。
一句话总结
- 别让 AI “讲讲整个代码库”。跑一套固定的五问序列：重要文件、请求生命周期、测试、未写出来的约定、以及”危险区在哪”。
- 用真能访问仓库的工具，而不是粘贴进聊天框。截至 2026 年 6 月，这指的是 Claude Code（Opus 4.7 上 100 万 token 上下文，可并行跑 Explore 子 Agent）、Cursor（Merkle 树索引每 ~5 分钟同步一次，已在 55 万文件以上验证）、或接了 GitHub 的 ChatGPT。
- 每个
file:line引用都点开核验。 错路径和编出来的函数是最常见的失败；让它”引用原文代码”，幻觉就会消失。 - 把答案用自己的话写进
CODEBASE-TOUR.md。预算 2–3 小时专注时间。当天 ship 一个小 PR，顺便验证你的 dev 环境。
这套流程解决什么
新仓库的迷糊不是不会读代码，而是不知道 5000 个文件里哪 50 个真重要。带仓库访问的 Agent 几分钟就能做完这个分流，而不是几小时。这篇给你精确的五问序列、答案归档格式、以及让你不至于交出一份”读着漂亮但一半是编的”导览的核验步骤。
它面向加入新项目、休假后回岗、或接外包前要审计代码库的开发者，也适合 staff / senior 被叫去”看看 X 服务”却毫无上下文的情况。5000 行以下的小仓库别用——一下午就能全读完；真正不能交给任何 AI 的专有代码也别用——那种情况跑本地模型或人工 walkthrough。
先选定工具
中途换 Agent 会丢上下文，所以先定一个。下面是三个现实选项在仓库导览上的对比（截至 2026 年 6 月）。
| 工具 | 怎么读仓库 | 上下文窗 | 最适合 | 注意 |
|---|---|---|---|---|
| Claude Code | 在仓库根直接读文件；/init 生成 CLAUDE.md 脚手架；可并行跑 Explore 子 Agent | Opus 4.7 上 100 万 token（一次对话约 2.5 万行代码） | Agent 自己读文件、跑命令的多步追问 | 子 Agent 的总结会抹平细节，引用仍要核 |
| Cursor | embedding 的 Merkle 树索引（存在 Turbopuffer），每 ~5 分钟自动同步，只重嵌改动文件 | 可跑 Sonnet 4.6、Opus 4.7、GPT-5.5、Gemini 3.1 Pro、Composer 2.5 | IDE 内边问边跳定义的探索 | RAG 检索可能漏掉跨文件关系；开跑前先把索引建满 |
| ChatGPT（GitHub connector） | 按需从连接的仓库 / 分支拉文件 | GPT-5.5；Plus 应用内约 320 页，完整 100 万只在 $200 Pro | 你常驻浏览器、不在 IDE 里时的快速查看 | connector 读取是受限的，大仓库只能看到局部 |
Claude Code 已打包进 Claude Pro（$20/月），Cursor Pro 也是 $20/月（年付约 $16）。已经付了其中一个就从那个开始。注意：Google 的 Gemini Code Assist 与 Gemini CLI 正被并入新的 Google Antigravity 平台——Google 已宣布这些扩展将于 2026 年 6 月 18 日停止为 Google AI Pro、Ultra 及免费个人版服务——所以它已不再是随手导览的当然第四选项。
开始前准备
- 本地 clone 好仓库，dev 环境能跑起来。你会跑命令来核验，
npm install一坏整个导览就卡住。 - 在
main（或当前活跃分支）上git pull。过期 checkout 等于在导览上季度的代码。 - 在草稿目录建一个空的
CODEBASE-TOUR.md。这是你的产出物。 - 留 2–3 小时不被打扰的时间。导览以文档写完为终点，不是以闹钟为终点。
- 用 Claude Code 的话，先跑
/init。它扫描仓库、检测框架与约定，写出一份起步的CLAUDE.md。把它当脚手架来改，不是当成品地图。
五问导览
按序跑完，一个 session 内，Agent 接着仓库。每一问都被刻意收窄成”必须给引用”，因为引用是你能去核的东西。
- 接上代码库。 Claude Code 在仓库根启动、Cursor 索引完全建好、或 GitHub connector 指向分支。没访问的纯聊天慢得多、也不好核验。
- 问题 1——重要文件。 “本仓库最重要的 5 个文件？每个一句话讲原因。给出 file path。”
- 问题 2——请求生命周期。 “从 URL 或入口走一遍 request lifecycle 到响应。每一跳给
file:line。“非 web 项目把”request lifecycle”换成”主数据流”或”从 CLI 调用到输出”。 - 问题 3——测试。 “测试怎么组织的？跑单文件 vs 全量测试的命令各是什么？按测试文件比例看，哪些目录 / 模块覆盖差？”
- 问题 4——未写出来的约定。 “哪些约定没写出来？找 README / CONTRIBUTING 没提、但代码里重复 3 次以上的 pattern。例子：命名、错误处理、日志、事务边界、文件布局。”
- 问题 5——危险区在哪。 “哪些文件改起来风险大？找老 TODO、
HACK/FIXME/DO NOT TOUCH注释、深嵌套条件、git churn 高的模块。” - 逐条核验。 每个被引文件按行号点开。AI 说
auth.ts:42是入口、但那文件 200 行里没 auth 逻辑——它在猜，换更紧的 prompt 重跑。 - 写成你的导览。 把答案用自己的话写进
CODEBASE-TOUR.md，附核验过的file:line。这是你的第一个 PR，也是你理解了的证据。
信之前先核
Agent 编行号比它自己承认的更频繁，所以核验这一步，正是把真导览和自信的虚构区分开的关键。
- 核每个引用路径。 文件里真有 AI 说的那段吗？错路径和过期行号是头号失败。
- 跑那条测试命令。 跑通绿了吗？跑不通就是猜的——去
package.jsonscripts、Makefile或 CI 配置里找真命令。 - 抽查危险区。 让团队里最 senior 的人只看这一段。外来者能捕到老人看不见的”未写约定”，但只有内部人知道哪些脆弱模块真会咬人。
- 干掉幻影函数。 AI 说有个函数”处理”什么、你却找不到，就换成”引用原文代码”重 prompt——幻觉函数会消失。
第一次怎么跑
第一遍别导览整库——先收窄范围。
- 挑一个子系统（auth、billing、search、或某个 job worker）。
- 五问只问这个子系统。
- 每条引用都点开核。记下 AI 哪些对、哪些错、哪些是幻觉。
- 第二轮只改一个变量——通常是 Agent（Claude Code vs Cursor）——看失败模式怎么变。一定会变。
把它变成可复用的习惯
- 5 条 prompt 存成
codebase-tour.prompts.md，跨工作带着走。 - 跑三次后你就知道哪条在你这栈下表现差，自己改——CLI 工具用”command dispatch path”而不是”request lifecycle”。
- 你已经熟的仓库大重构后，跑迷你导览（只问 3 条）。代码库会漂移，README 里的架构图基本已经过期。
- 第二天挑最小可行贡献（typo、文档、缺测试）ship 出去。既验证 dev 环境，又留下能力凭证。
容易踩的坑
- 问”全讲讲”。拿到读着不错、帮不到的总结。每问都收窄范围、都要引用。
- 不点开核
file:line就信。 - 跳过危险区那问，觉得第一天问不礼貌。那些是你第二个月会踩的坑。
- 把导览当成品。真理解只能靠改代码；导览是地图，不是疆域。
- 让 Agent 编模块名。路径不存在就明说并重 prompt，别糊弄过去。
FAQ
- Cursor 还是 Claude Code？ IDE 内边问边跳定义用 Cursor，它的索引每 ~5 分钟同步、已在 55 万文件以上验证；要 Agent 自己读文件、跑命令的多步追问用 Claude Code，Opus 4.7 上有 100 万 token 上下文。两个都行——从你已经付费的那个开始。
- NotebookLM 呢？ 库里有大量写好的设计文档可上传时好用。对裸源代码，能直读仓库的 Agent 更强，因为它能跟着 import 走，而不是猜。
- 多大的库这套就不灵？ 大概超过 50 万行 / 1 万文件，即便 100 万 token 的模型上下文窗也开始挤。一次只导览一个子系统，靠 Cursor 的索引或 Claude Code 的 Explore 子 Agent 做检索。
- 导览文档要发给团队吗？ 队友核过危险区那段后发。新人写的 onboarding 文档经常捕到老人已经看不见的”未写约定”。
- 库里完全没测试怎么办？ 那本身就是问题 3 的答案。在导览里标成风险，并想清楚你还要不要 land 在这。
- 私有仓库不能上传代码怎么办？ 可以——Claude Code 在本地对着你的 checkout 跑，Cursor 会加密文件路径、从不以明文存源码。但把任何工具指向专有代码前，先确认服务商的数据处理政策。
相关阅读
Cursor 索引机制的官方说明见 Cursor 的 codebase-indexing 文档；Claude Code 见 Anthropic 的 best-practices 指南。