跳转到内容
Claude Code Tutorial

探索陌生代码库

探索陌生代码库

Section titled “探索陌生代码库”

接手一个陌生代码库，就像走进一栋没去过的大楼——走廊交错、房间上百，你不知道哪间是会议室、哪间是储藏室。传统做法是打开编辑器一个个文件翻，半天下来还在转圈。

Claude Code 让这件事快一个数量级。它会替你读、替你找、替你画地图，你只需要会问问题。

第一步：站在门口，按下启动键

Section titled “第一步：站在门口，按下启动键”

进入项目根目录，敲下两个字符：

Terminal window
cd path/to/the/project
claude

「站在门口」很重要——Claude Code 启动时会把当前目录当成上下文根，跑 ls、读 README、扫 package.json 都从这里开始。从 ~/Downloads 启动再让它 cd 进项目，会多绕一圈。

第二步：先要一张全景图

Section titled “第二步：先要一张全景图”

不要一上来就问具体函数。先让它给你整栋楼的导览图：

give me an overview of this codebase

Claude 会扫一遍目录结构、读 README 和 manifest 文件，告诉你：这是什么项目、用什么技术栈、入口在哪、目录怎么分层。

如果项目复杂，可以再追问架构层：

explain the main architecture patterns used here

它会识别出你用的是 MVC、分层架构、六边形架构、还是事件驱动，并解释每一层在哪、负责什么。这比逐个翻 src/ 高效得多。

第三步：锁定关键数据模型

Section titled “第三步：锁定关键数据模型”

代码可以乱，但数据模型通常是清晰的——它反映业务的真实形状。把它摸清，你就抓住了项目的脊椎：

what are the key data models?

Claude 会列出核心实体（用户、订单、会话……）、它们的关系、字段含义、以及它们在哪些文件里被定义和操作。看完这一段，你心里就有了「业务骨架」。

第四步：把脏活交给 Explore 子代理

Section titled “第四步：把脏活交给 Explore 子代理”

上面三步如果你亲自问，主上下文已经开始塞东西了——README 全文、目录树、几个核心文件的源码。再问两轮，注意力就开始稀释。

更好的做法是委托。直接对主代理说：

use the Explore subagent to find all places where the authentication token is validated, and report back the call chain

Explore 子代理拿到任务后，会开一份干净的上下文，自己跑 Grep、读文件、交叉验证，最后只把摘要交还主代理。主代理的笔记本里只多了一段总结，而不是几千 token 的过程。

三档力度按需选：

档位 适合
fast 找一个函数/变量在哪定义
medium 理解一个模块怎么工作
very thorough 整体摸排陌生项目

第五步：理解数据流，而不只是看代码

Section titled “第五步：理解数据流，而不只是看代码”

光知道「这个函数在哪」不够，你要知道「数据是怎么流动的」。这是从「读懂代码」到「理解系统」的分水岭：

trace how a request flows from the HTTP handler in src/api/ through the service layer down to the database. draw the call chain
where does user input get sanitized? list every entry point and the sanitization applied

这种问题让 Claude 不是孤立地看文件，而是沿着调用链走——一个函数跳到下一个，跳完告诉你整条路径。这种「路径式」理解，是探索代码库最有价值的产出。

一份可复制的探索脚本

Section titled “一份可复制的探索脚本”

接手新项目时，把下面这一串 prompt 依次丢给 Claude，基本能把任何陌生代码库摸到七成：

1. give me an overview of this codebase
2. explain the main architecture patterns used here
3. what are the key data models?
4. use the Explore subagent to map the call chain from the entry point to the core business logic
5. where are the tests? what framework? what's the coverage like?
6. summarize in 10 bullets: if I want to add a new API endpoint, what files do I touch?

最后一条尤其有用——它把所有探索结果收束成一个 actionable checklist，下次你想动手时直接照着做。

探索时的几个小纪律

Section titled “探索时的几个小纪律”
  • 保持只读心态：探索阶段别让 Claude 改东西。读多了会污染上下文，还可能误改坏。
  • 善用 @ 引用：想让它看某个文件，直接 @src/auth/login.ts，比解释半天路径快。
  • 要图，不要散文：让它「列出」「画调用链」「给表格」，比让它「详细描述」更易消化。
  • 委托，委托，再委托：所有「找一下哪里」「读一下这个」的活，都丢给 Explore 子代理。

下一站

Section titled “下一站”