Onboarding Unknown Codebase

---
name: onboarding-unknown-codebase
description: 需快速上手陌生代码库、理解项目结构时。
---

# 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 和包清单 |
| 只口头讲不产出 | 给用户一份结构化地图 |
| 试图读完所有文件 | 只读主干，标记跳过分支 |