4.1 探索陌生代码库

接手别人的代码，是一种什么体验

每个开发者都经历过这个场景：

打开一个从没见过的代码库，里面有几百个文件，没有文档，上一个维护者已经离职，你需要在三天内搞清楚它是怎么工作的，然后修一个 bug。

以前这叫"痛苦"。有了 Claude Code，这叫"一个下午的事"。

---

探索的正确姿势：从宏观到微观

不要一上来就问某个具体文件是干什么的——先建立全局认知，再往下钻。

第一层：整体概览

give me an overview of this codebase — what does it do,
what's the tech stack, and how is it structured?

explain the main architecture patterns used in this project

Claude Code 会读取 README、package.json、目录结构，给你一个整体描述。这一步建立的是"地图"。

第二层：找关键路径

where is the main entry point? trace the request flow
from the entry point through the key modules

what are the core data models? show me how they relate to each other

how is authentication handled? which files are involved?

这一步找的是"主干道"——最重要的几条执行路径。

第三层：深入具体模块

explain how the payment module works in detail.
walk me through the code flow when a user makes a purchase

what does src/services/UserService.ts do?
are there any parts that look risky or poorly implemented?

这一步才到具体文件和函数。

---

接手项目的标准 prompt 清单

以下是一套可以直接用的 prompt，按顺序执行，基本能覆盖一个项目的核心认知：

# 1. 整体认知
what does this project do? summarize in 3-5 sentences

# 2. 技术栈
what technologies, frameworks, and libraries does this project use?

# 3. 目录结构
explain the folder structure. what is each main directory responsible for?

# 4. 如何运行
how do I run this project locally? what are the setup steps?

# 5. 如何测试
what testing framework is used? how do I run the tests?
are there any known flaky tests I should be aware of?

# 6. 找到核心
what are the most important files in this codebase?
which files would I need to understand first?

# 7. 找隐患
looking at the codebase, what areas seem most risky or brittle?
what would you flag for a new developer joining this project?

最后一个 prompt 特别有价值——让它从"新人视角"扫一遍，往往能发现一些老代码库里埋藏多年的地雷。

---

用 @ 引用特定文件

探索过程中，如果你想让它专注于某个特定文件：

look at @src/core/Engine.ts and explain what it does.
why does it use this pattern instead of a simpler approach?

compare @src/auth/JWTStrategy.ts and @src/auth/OAuthStrategy.ts.
what are the key differences?

@ 引用会让 Claude Code 优先读取这些文件，而不是让它自己决定从哪里开始。

---

探索完之后做什么

探索阶段结束后，有两件事值得做：

1. 让它帮你生成 CLAUDE.md

如果这个项目还没有 CLAUDE.md，或者现有的 CLAUDE.md 不完整，在你理解了项目之后让它生成：

based on what you've learned about this project,
generate a CLAUDE.md that would help future developers
(including yourself in a new session) get up to speed quickly.
include build commands, key architectural decisions, and gotchas.

2. 用 /clear 重置上下文

探索阶段会产生大量上下文（读了很多文件），但这些文件的原始内容在接下来的任务里不一定用得上。探索完之后 /clear，保留你从 CLAUDE.md 里能恢复的基础背景，开始正式的开发任务。