---
title: "基础代码理解"
description: "接手陌生仓库时，先让它画地图再钻细节：按固定框架读文件、追一条完整调用链、用四种提问手法核对理解，最后边跑边看。"
updated: 2026-11-13
canonical: https://docai.cc/learn/basic-code-comprehension/
markdown_mirror: https://docai.cc/learn/basic-code-comprehension.md
---
## 先要地图，再钻细节

接手别人的仓库，最常见的错误是从第一个文件开始逐行读。读了一下午，还是说不清请求从哪里进来、数据最终存到哪里。换个顺序：先让它讲整体，再按需深入。还没完整跑通过一次上手流程的，可以先看[第一次上手怎么做](/learn/claude-code-first-run/)。

## 单个文件：给一个固定框架

> 读一下 src/auth 下的会话管理文件，按这个顺序讲：
> 1. 核心数据结构有哪些字段，各自存什么；
> 2. 每个导出函数做什么，被谁调用；
> 3. 安全与性能上值得警惕的点。
> 不确定的地方直接说，不要猜。

把想要的输出形状一起交代，比只说「解释这个文件」信息量大得多。第一遍要它讲人话，不要逐行翻译语法：你需要的是模块的职责与边界，不是关键字注释。

如果某一节讲得含糊，就单独追问那一节。比如「第 2 点里那个刷新函数，谁在什么时机调用它」，比笼统的「再详细点」有效。

## 追一条完整调用链

> 用户提交订单之后，从路由入口一直到写入数据库，按执行顺序列出经过的文件、函数和关键判断。
> 每一步用一句话说明它在做什么；找不到出处的地方明确标出来。

前端场景类似：按钮点击后，事件处理、发请求、更新状态、重新渲染，一路追到底。碰上异步任务，问清楚回调或队列在哪一环接上。链条里出现你不认识的模块，就当场展开，别攒到最后一起问，问题堆多了上下文容易乱。

## 项目级：先要三张图

接手新项目，先要三样东西：

- 目录职责：每个顶层目录放什么，入口在哪；
- 技术选型：语言、框架、数据库、构建工具，各负责哪一层；
- 数据流：一次典型操作从界面到存储再回到界面，经过哪些环节。

如果仓库拆成多个包，再补问包之间的依赖方向与本地启动顺序。拿到这三张图，你才知道该先看哪里，也才知道哪些地方看不懂属于正常。图不用画得漂亮，能说清谁调用谁、数据在哪一步停下来，就够用。

## 四种提问手法

| 手法 | 适用场景 | 示例 |
|---|---|---|
| 由整体到局部 | 刚接触一个模块 | 先讲整体职责，再展开某个具体函数 |
| 对比两处实现 | 同一件事有两种写法 | 两处错误处理有什么区别，各适合什么情况 |
| 复述验证 | 自认为看懂了 | 我理解这个函数先校验再写入，对吗，漏了什么 |
| 追问设计原因 | 遇到看似奇怪的选择 | 为什么这里用弱引用缓存，换成普通字典会怎样 |

复述验证最容易被跳过，却最有用。你讲一遍，它挑错，比被动听讲记得牢。问题一次只问一个，答案更容易核对。遇到关键设计，多问一句「如果不这样做会出什么问题」，往往能问出真正的约束。上下文变长后，早期结论容易被冲淡，重开一段对话之前记得把结论记下来。

## 定位实现：从一个行为倒推文件

很多时候你不是要读懂某个文件，而是要知道某件事在哪儿发生。描述你观察到的行为，让它去找：

```text
用户连续输错密码五次后账号会被锁定十分钟。
请找到实现这段逻辑的位置，按下面格式回答：
1. 入口文件与函数；
2. 计数存在哪里，用什么类型；
3. 锁定与解锁分别由什么触发；
4. 有没有配置项可以调整次数和时长。
不确定的地方标注「推测」，并说明依据。
```

「推测」两个字很重要。按关键词搜索常常命中多个相似实现，模型可能挑一个看起来最像的当答案。要求它标出依据，你就能按路径去核实；命中多处时，让它按调用关系排序，说明哪一处真正会在运行时生效。查不到就回答查不到，不要让它编一个不存在的函数名。需要它直接读取仓库时，做法见[让模型读文件](/learn/let-model-read-files/)。

## 难代码怎么读：先问约束，再问取舍

缓存淘汰、并发控制、状态管理这类代码，难点不在语法，而在设计动机。提问时把「解决什么问题」放在「怎么实现」前面：

```text
解释这个缓存模块的淘汰策略，分三层：
1. 它要满足的约束是什么（容量、过期、并发访问）；
2. 具体做法是什么，关键数据结构和判断在哪几行；
3. 如果换成最朴素的写法，会先坏在哪一步。
```

第三问最有价值。它往往会告诉你，朴素写法在什么量级下开始退化、哪个场景先出问题，这比逐行翻译更能帮你判断要不要动它。读配置文件和第三方库时同理：先问这项配置改变了什么行为，再问默认值是什么，最后问改错会怎样。

## 边跑边看，不必读完整个仓库

把项目跑起来，按一条真实操作路径走一遍，再回到代码里对照。日志、断点、请求记录，都能帮你把「代码里写的」和「实际发生的」对上。对不上，通常就是理解偏差最大的地方。

阅读顺序建议：全局概览、核心流程、关键模块、具体问题。不需要等仓库全部读完再动手，按任务需要深入，效率更高。

读懂了才有底气改。下一节讲怎么在不动坏原有行为的前提下修改：[代码修改与优化](/learn/code-modification-optimization/)。