Onboarding unknown codebase

Onboarding Unknown Codebase

概述

用一套分层流程把陌生代码库变成一张"项目地图"，而不是一头扎进某个文件读细节。核心：先建立全局心智模型，再按需深入。

何时使用

• clone 了新项目，不知从哪读起
• 接手别人的代码（同事离职、新入职）
• 要给别人讲清楚一个项目
• 想搞清某个项目的整体架构/数据流

不该用：只想找某个具体函数/bug（直接搜）；项目你已经熟了。

核心内容

先确认对象（前置）

三遍法假设你已经拿到目标代码库。但用户常只说"帮我梳理这个项目""讲讲这个代码库"却没给路径——这是高频形态。开跑前先确认对象：

• 有明确本地路径或 git 地址 → 直接进入三遍法
• 没给 → 先向用户要：本地路径、git 地址、或至少 README.md + 包管理清单（package.json/go.mod 等）+ 顶层目录树（tree -L 2）。拿到这三样就能完成第一遍宏观 + 第二遍结构骨架
• 不要默认当前工作目录就是目标，更不要凭空臆造一个项目来梳理——那会跑题

三遍法

第一遍·宏观（5-10 分钟，别读代码） 读"元信息"文件，搞清"这是什么、技术栈、怎么跑"（按项目实际有的读，没有的就跳过）：

• README.md —— 项目用途、怎么跑起来
• 包管理清单：package.json / go.mod / Cargo.toml / requirements.txt —— 技术栈、依赖
• Dockerfile / docker-compose.yml —— 怎么部署（库/CLI 项目通常没有）
• CI 配置：.github/workflows/ —— 怎么构建测试
• 配置：.env.example、config/ —— 运行时配置

第二遍·结构（10-15 分钟） 看目录布局和分层，建立"地图骨架"：

• 顶层目录各自负责什么？（src/ 源码、tests/ 测试、docs/ 文档）
• 分层模式：前后端分离？MVC？分层架构？
• 入口在哪？（main、index、app、server；库/CLI 项目最快的方式是看 package.json 的 bin 和 exports 字段）
• 模块之间怎么依赖（谁调用谁）

第三遍·主线（15-30 分钟） 从入口顺一条核心调用链读到底，不求全：

• 入口启动后，处理一个典型请求/操作，经过哪些模块？
• 只读主干，遇到分支先标记跳过
• 这条链路走通，就理解了项目的"骨架动力"

不同项目类型的主线形态不同——别用同一把尺子：

类型	入口找法	主线追踪什么
服务型（web/api）	server.listen / app.run / 路由表	一次请求的链路：HTTP 进来 → 中间件 → controller/handler → service → 数据层 → 响应
库 / SDK	package.json 的 exports、go.mod 主包、__init__.py 暴露的符号	一次典型函数调用：公开 API 入口 → 内部参数校验 → 核心算法/数据变换 → 返回值组装
CLI	bin 字段、main 函数、命令注册表	一次典型命令的执行：参数解析 → 子命令分发 → 业务逻辑 → 输出/副作用

库项目的常见坑是"没有明显的请求入口"——这时从**公开 API（exports/导出符号）**切入，挑一个最常用的函数，顺它的调用栈读到底，等价于服务型项目的"一次请求"。

产出：项目地图

给用户一份结构化地图（不是流水账）：

## 这是什么        <一两句：项目用途>
## 技术栈          <语言、框架、关键依赖>
## 目录结构        <顶层目录职责 + 入口位置>
## 核心流程        <从入口出发的主调用链，逐步>
## 关键文件        <最重要的 3-5 个文件及职责>
## 怎么跑起来      <安装、配置、启动命令>

边界

• 先地图后细节：别一上来读某个函数实现
• 不求全：80/20，先懂主干
• 产出要结构化：口头散讲不如一份地图

常见错误

问题	修法
一上来深挖某文件	先宏观再结构，最后才深入
不看配置就猜架构	第一遍先读 README 和包清单
只口头讲不产出	给用户一份结构化地图
试图读完所有文件	只读主干，标记跳过分支