Explore Codebase Prompt：让 AI 快速读懂陌生代码库

用法

接手新仓库 / 接手别人代码时，让 AI 先产出一份「代码库地图」，再针对具体任务深入。比直接问「这段干嘛的」效率高得多——先有全局，再有局部。

Prompt

你刚接手下面这个代码库，需要在 30 分钟内搞清它的脉络。请产出一份给人看的导航，不要逐文件翻译。

# 输出结构
1. 一句话定位：这个仓库是做什么的、给谁用。
2. 入口地图：程序从哪里启动 / 请求从哪里进（main / 路由 / handler），画一条「请求 → 核心逻辑 → 数据」的链路。
3. 核心模块：3-5 个最关键的文件/目录，各自负责什么、彼此怎么依赖。
4. 数据流：配置从哪来、状态存在哪、外部依赖（DB / API / 队列）接在哪儿。
5. 上手路线：一个新功能 / 一个 bug 该从哪个文件开始读。
6. 坑点预警：哪里的命名有迷惑性、哪里的隐式依赖最容易踩、哪里文档和代码对不上。

# 约束
- 只基于仓库里真实存在的东西下结论，路径要能给到 `文件:行号`。
- 不确定就说不确定，标「待确认」，不要编调用关系。
- 用「新人视角」写，假设你完全不了解这个业务。

<粘贴仓库结构 / 关键文件路径，或让 Agent 直接读仓库>

为什么有效

• 先地图后细节：强制模型先建全局认知，避免陷入某个文件钻牛角尖。
• 链路 > 翻译：给「请求怎么走」比给「这个函数在干嘛」有用十倍，因为新人最缺的是端到端视角。
• 坑点预警：把「命名误导 / 隐式依赖」点出来，省下新人踩坑的半天。
• 文件:行号 约束：结论可验证，不编依赖。

进阶（自动化）

让 Claude Code 直接读仓库后生成导航文档，落到 docs/ 或仓库 README 的 "Architecture" 段：

# 让 Agent 读仓库并产出地图
claude -p "按 explore-codebase 模板摸清本仓库，输出导航到 docs/codebase-map.md"

反例（AI 默认会写的烂导航）

「user.ts 定义了 User 类，order.ts 定义了 Order 类……」——逐文件罗列，没有脉络。 「请求从 app.ts:42 的 /checkout 进 → cart.service.ts:18 算价 → pay.gateway.ts 调三方 → 落 orders 表；新功能从 cart.service.ts 读起。」

「这个仓库架构清晰、易于扩展。」——空话，新人得不到任何 actionable 信息。 「config.ts:30 的 getEnv() 实际读的是 .env.local 而非 .env，文档写反了，启动前先核对。」

什么时候用 / 别用

该用：

• 接手陌生仓库或别人写的模块，需要先建全局认知
• 入职 / 转岗 / 接手离职同事代码的第一天
• 评估一个开源项目值不值得引入（先看地图，再决定读不读源码）
• 准备做跨模块重构前，先摸清依赖面

别用：

• 你自己就是作者、或对这块代码已经很熟——直接问具体问题更快
• 极小仓库（十来个文件）：人肉读一遍比等它生成快
• 只想知道某一个函数在干嘛——用精确提问，不要启动全局导航
• 仓库里根本没有构建 / 入口线索（比如一堆散装脚本）：模型会硬编一条链路出来，这正是下面「验收判据」要挡的情况

验收判据（怎么判断它给的地图是真的）

别只看它写得像不像，按这四条抽查：

1. 抽 3 个 文件:行号 亲自打开看——这是最重要的一条。行号对不上，说明它在编；编出来的地图比没有地图更危险，因为你会照着它去改代码。
2. 顺着它给的链路走一遍——从入口到数据落库，每一跳都要能在代码里找到。中间跳了一步，那条链路就是猜的。
3. 看「坑点预警」那一段有没有具体内容——只写「架构清晰、易于扩展」的，等于没做；能指出「文档写的和实际读的文件不一致」的，说明它真的读了。
4. 拿一个你知道答案的问题去考它——比如「配置从哪个文件读的」。答错就整份作废，不要只修那一条。

判据背后的原理：这份 prompt 的核心价值是可验证性，而不是文采。上面的 文件:行号 约束就是为此存在的——验收时不抽查行号，等于放弃了唯一能证伪它的手段。

变体

变体 A —— 新人 onboarding（偏教学） 在约束段追加：用「新人视角」写，每个模块附一句「如果你要改 X，就来这里」。不要出现「显然」「众所周知」这类措辞。

变体 B —— 重构前摸底（偏风险） 把输出结构第 6 项换成：6. 改动风险面：哪几个模块被引用最多、哪些地方有隐式耦合、哪里一改就牵连测试。按风险从高到低列出。

变体 C —— 只追一条链路（偏精准）

只追这一条链路：<具体的用户动作或 API 调用>。
从入口到数据落库，每一跳给 文件:行号，并标出每一跳做的转换。
不要描述链路之外的模块。

批量跑 / 接管道：

# 只输出结论，接进文档流水线
claude -p "按 explore-codebase 模板摸清本仓库，只输出 markdown，不要解释" > docs/codebase-map.md

# 多个仓库批量生成地图
for d in service-a service-b service-c; do
  (cd "$d" && claude -p "按 explore-codebase 模板输出导航，只输出 markdown" > "../maps/$d.md")
done

延伸阅读

• 架构评估：Tech Architecture Eval Prompt
• 编码范式：Agentic Coding
• 上下文管理：Context Engineering