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 分钟） 从入口顺一条核心调用链读到底，不求全：

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

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

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

产出：项目地图

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

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

边界

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

常见错误