学习大型代码库：不要通读，先建立地图

第一步：先验证项目是否可信#

在投入时间前，先看几个基础信号：

• 是否有明确的依赖清单，例如 package.json、Cargo.toml 或 pom.xml；
• 是否有 README、许可证和版本控制痕迹；
• 是否存在锁文件与测试目录；
• 入口脚本和构建脚本是否能对应起来。

这一步并不保证项目安全，但能快速发现不完整 dump、伪源码或无法复现的资料。

第二步：只扫顶层，不钻细节#

先获得这些信息：目录树两层、主要语言、最大文件、配置入口、构建命令、测试命令。

目标不是理解代码，而是知道系统的边界。比如一个 Web 项目通常会有入口、路由、状态管理、数据访问和 UI 五类区域；一个 Agent 项目则常见主循环、工具层、记忆层、模型适配层和权限层。

第三步：挑 5 到 7 个文件精读#

优先级一般是：

1. 程序入口和主循环；
2. 最核心的抽象或接口；
3. 状态机、任务调度或数据流；
4. 外部通信和持久化；
5. 最重要的一个业务子系统。

不要一开始读工具函数、图标组件或零散配置。它们重要，但通常不能解释系统的骨架。

第四步：每读一处，都记录“为什么”#

笔记不应只是代码摘抄。每个核心文件可以记录：职责、输入输出、依赖关系、失败方式，以及它与其他模块的连接点。

当这些笔记串起来时，代码库会从文件集合变成一张可讨论的架构图。

大型代码库的学习，本质不是阅读速度竞赛。关键是先定位少数能解释全局的杠杆点，再向外扩展。