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/导出符号）切入，挑一个最常用的函数，顺它的调用栈读到底，等价于服务型项目的"一次请求"。

产出：项目地图

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

## 这是什么        
## 技术栈          
## 目录结构        
## 核心流程        
## 关键文件        
## 怎么跑起来      

边界

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

常见错误

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Lion-1209
• Source: Lion-1209/Lion-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.