AI Agent / 系统课时
浏览与理解代码库
浏览与理解代码库
面对陌生代码库,不要让 Claude Code 一上来就“解释整个项目”。更高效的做法是先建立结构视图,再围绕一个符号或业务流程向下追踪,并要求每个结论都给出文件证据,最后用测试和配置文件交叉验证理解。
学习目标
- 用由宽到窄的提问方式快速建立代码库地图
- 让 Claude Code 定位文件、搜索符号并追踪调用关系
- 用文件路径、关键实现和测试证据验证模块关系
先建立代码库地图
从项目根目录启动会话后,先明确“只读分析,不修改文件”,再让 Claude 找入口、主要目录、依赖清单、测试目录和项目级说明文件。这个阶段的目标是获得导航地图,而不是把每个文件都读一遍。
bash
cd <PATH>
claude预期结果
text
Claude Code 进入以 <PATH> 为工作目录的交互会话。随后输入一个范围清晰的探索请求:
text
先只读分析,不修改文件。请概览这个代码库:
1. 找出主要入口、核心源码目录、测试目录和依赖/构建配置。
2. 用 5~8 条说明各目录职责。
3. 每条结论都附上对应文件路径;不确定的地方明确标注。预期结果
text
返回一份按目录和职责组织的代码库概览,并给出可继续深入的文件路径,而不是直接修改代码。从符号追到调用链
理解具体功能时,优先从“符号”或“业务动作”切入。例如要研究登录流程,不只问“认证怎么做”,而是要求 Claude 找定义、引用、调用者、下游依赖和测试。这样能把自然语言解释绑定到真实实现。
text
请定位处理“用户登录”的主要入口和核心符号,然后按下面顺序分析:
- 定义在哪个文件
- 谁调用它
- 它继续调用哪些服务或数据访问层
- 失败分支在哪里处理
- 哪些测试覆盖了这条路径
最后给出一条从入口到数据层的调用链,并附文件路径和关键行号。预期结果
text
得到“入口 → 核心逻辑 → 下游依赖 → 数据访问/外部服务 → 测试”的可核对链路;每个节点都能回到具体文件,而不是只有抽象描述。
用显式引用缩小范围
当你已经知道目标文件或目录时,可以在提示中使用 @ 引用,避免每次让 Claude 重新猜范围。例如 @src/auth/ 可用于要求它先查看该目录结构,@src/auth/service.ts 则可把单个文件直接作为当前问题的上下文。
text
请基于 @src/auth/ 梳理这个目录内各文件的职责,并说明它与项目其他模块的依赖方向。先解释,不要修改。预期结果
text
分析范围集中在指定目录,并把目录内文件与外部依赖关系分开说明。目录引用适合先看结构,单文件引用适合逐行解释;如果真正的问题跨越多个模块,再让 Claude 继续搜索调用方和引用点,不要把一个局部文件误当成完整业务流程。
验证解释而不是接受解释
高质量的代码库理解必须能被源码复核。让 Claude 在最终结论中区分“直接从代码看到的事实”和“根据命名或结构做出的推断”,并优先检查入口文件、配置、类型定义、测试与最近相关实现。
当你能从一个业务动作反向找到入口、核心符号、依赖和测试,再正向复述一次调用链,就说明已经获得足以继续开发的代码库模型。下一步无论修 Bug 还是新增功能,都应基于这条已核对的证据链继续工作。
按自己的节奏,确认真正理解。