跳到主内容
exploreonboardingcodebasearchitecture

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

让 AI 用「先画地图、再追调用链、最后给上手路线」的方法摸清陌生仓库：识别入口 / 核心模块 / 数据流 / 坑点，输出一份给人看的导航，而不是逐文件翻译。

适用：Claude CodeCursorAiderCodex

用法

接手新仓库 / 接手别人代码时，让 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，文档写反了，启动前先核对。」

延伸阅读