进新代码库以前要一周点目录、两周结对、一个月才能 land 非琐碎 PR。现在有能直读仓库的 Agent，同样的”入门”压成专注的一天就行——前提是按对的顺序问对的问题，并把答案落到自己的文档里。这是任何新加入项目或几个月后回到老项目的开发者第一天就该跑的仪式。
这篇主要解决什么问题
新仓库的迷糊不是因为不会读代码，而是不知道在 5000 个文件里哪 50 个真重要。带仓库访问的 AI 几分钟就能完成这个分流。这篇给你五问的精确序列、答案归档格式、以及核验步骤——别把全是幻觉的 AI 导览当结论。
这篇适合谁看
加入新项目、休假后回岗、接外包前要审计代码库的开发者。也适合 staff / senior 被叫去”看看 X 服务”时没上下文的情况。5000 行以下的小仓库别用——一下午就能全读完。
什么时候适合用
新工作 / 新轮岗第 1 天。也用在：你自己的项目隔 3 个月再开、接管被弃的内部工具、给从未碰过的仓库做 code review。在你写第一行新代码之前跑。
什么时候不建议用
既没文档又不能给 Agent 访问的代码库（不能上传、不能分享、只能一次 2000 行粘贴）——比直接读代码还慢。或者真正不能交给任何 AI 的专有代码（即便自托管）——这种用本地模型或人工 walkthrough。
开始前准备
- 选定 AI：Claude Code 在 checkout 的仓库根、Cursor 索引建好、GitHub connector 的 ChatGPT、或 Gemini Code Assist。挑一个——中途切换会丢上下文。
- 本地 clone 好仓库，dev 环境能跑起来。你会需要跑命令来核验。
- 在草稿区建空
CODEBASE-TOUR.md。这是产出物。 - 留 2-3 小时不被打扰的时间。导览以文档写完为终点，不是以闹钟为终点。
具体步骤
- 接上代码库。 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——也是你理解了的证据。
第一次实操怎么跑
- 挑一个子系统（auth、billing、search、某个 job worker），不要整库。
- 五问只问这个子系统。
- 每条引用都点开核。记下 AI 哪些对、哪些错、哪些是幻觉。
- 第二轮只改一个变量——通常是 Agent（Claude Code vs Cursor）——看失败模式有没有变。会变。
完成后检查
- 每个引用路径，文件里真有 AI 说的那段吗？错路径和过期行号是最常见的失败。
- AI 给的测试命令你能跑通绿吗？跑不通就是猜的——去
package.json/Makefile/ CI 配置里找真命令。 - “危险区”答案和团队 senior 说的对得上吗？让 senior 重点抽查这一段。
- 有没有 AI 在描述根本不存在的代码（说有个函数”处理”什么、但你找不到）？换成”引用原文代码”重 prompt——幻觉函数会消失。
怎么复用这套流程
- 5 条 prompt 存成
codebase-tour.prompts.md，跨工作带着走。 - 跑三次后你就知道哪条在你这栈下表现差，自己改——比如 CLI 工具用”command dispatch path”而不是”request lifecycle”。
- 你已经熟的仓库大重构后，跑迷你导览（只问 3 条）。代码库会漂移。
建议的操作流程
新工作第一天：2-3 小时专注，Agent 接仓库，5 问按序，产出 CODEBASE-TOUR.md 带核验过的 file:line 和你自己的标注。开 PR 加到 docs/ 或个人 wiki。第二天 70% 的”从哪开始”摩擦消失，并给下一个新人留下可复用文档。
容易踩的坑
- 问高层次问题”全讲讲”——拿到读着不错但帮不到的总结。
- 不点开核
file:line就信。Agent 编行号比它自己承认的更频繁。 - 跳过”危险区”，觉得第一天问这个不礼貌。这些是第二个月会踩的坑。
- 把导览当成品。真理解只能靠改代码；导览是地图，不是疆域。
- 让 Agent 编模块名。路径不存在就明说并重 prompt，别糊弄过去。
- 在过期分支上跑导览。先 pull
main，否则你在导览上季度的代码。
进阶技巧
- 每个”重要文件”当天自己读前 200 行。AI 提示 + 人读 = 真理解。
- 导览后挑最小可行贡献（typo、文档、缺测试）ship 出去。验证 dev 环境，也留下能力凭证。
- 大重构或新增核心依赖后重做导览。README 里的架构图基本已经过期。
- 第 2 天和队友 pair 跑一遍。他们会纠 AI 错的地方，你看着也不像新来的。
FAQ
- Cursor 还是 Claude Code？: IDE 内边问边跳定义用 Cursor；要 Agent 多步自己读文件用 Claude Code。两个都行，挑你已经付费的。
- NotebookLM 呢？: 有大量写好的设计文档可上传时好用。对裸源代码，能直读仓库的 Agent 更强，因为能跟着 import 走。
- 多大的库这套就不灵？: 大概超过 50 万行 / 1 万文件，Agent 上下文窗就开始挤。一次只导览一个子系统。
- 导览文档要发给团队吗？: 队友核过”危险区”后发。外来人写的 onboarding 文档经常捕到内部老人看不见的”未写约定”。
- 库里完全没测试怎么办？: 那就是问题 3 的答案。在导览里标成风险，并想清楚你还要不要 land 在这。
- 私有仓库不能上传代码怎么办？: 自托管模型或本地跑 Claude Code 能解。粘任何专有代码前先确认 AI 服务商的数据处理。