快速理解新 Codebase：前三天該做什麼
不要從
main.ts第一行開始讀。那是最慢的方式。
這篇要解決的問題
每個工程師都會遇到：
- 換工作，第一天面對一個幾十萬行的 codebase
- 接手同事的專案，「他下週就離職了」
- 開源專案要改一個 bug，但整個架構看不懂
大部分人的直覺是「從頭開始讀 code」。這是最慢的方式，因為你不知道哪些重要、哪些不重要。
正確的方式是：先建立全景，再深入細節。 就像看一張地圖——你不會從左上角開始一個像素一個像素地看。
Day 1：建立全景
目標：能在白板上畫出系統的粗略架構圖。
1.1 先看「外面」，不看 code
README.md → 專案目的、怎麼跑起來
package.json → 用了什麼框架和套件
docker-compose → 系統有幾個組件
.env.example → 連了哪些外部服務
CI/CD config → 怎麼部署、跑了哪些測試
從這些檔案你能知道：
- 這是前端/後端/全端？
- 用了什麼框架？（Express? Next.js? Django?）
- 有幾個服務？（monolith? microservice?）
- 依賴哪些外部系統？（資料庫? Redis? 第三方 API?）
1.2 看目錄結構
# 只看前兩層
tree -L 2 -d
# 或者
ls -la src/目錄結構通常反映架構。常見的模式：
| 結構 | 代表什麼 |
|---|---|
src/controllers/ src/models/ src/routes/ | MVC 架構 |
src/users/ src/orders/ src/payments/ | Domain-driven / Feature-based |
packages/api/ packages/web/ packages/shared/ | Monorepo |
src/pages/ src/components/ src/hooks/ | 前端 (Next.js / React) |
1.3 畫一張架構圖
不需要完美。用 30 分鐘畫出：
- 有哪些主要組件（前端、API、資料庫、第三方服務）
- 它們之間怎麼連接
- 資料的主要流向
[使用者] → [前端 Next.js] → [API Express] → [PostgreSQL]
↓
[Redis Cache]
↓
[Stripe API 支付]
這張圖接下來三天你會反覆修正。 第一版不對很正常。
1.4 讓它跑起來
在 Day 1 結束前，一定要把系統跑起來。不管用多髒的方式。
# 照著 README 做
npm install
docker-compose up
npm run dev
# 如果跑不起來，記下卡在哪
# 這些坑本身就是很有價值的資訊能跑起來之後，用瀏覽器/Postman 操作一遍主要功能。用使用者的角度走一遍 happy path。
Day 2：追蹤一條關鍵路徑
目標：理解一個核心功能從 request 到 response 的完整流程。
2.1 選一條路徑
選系統最核心的功能。不要選最簡單的（太淺），也不要選最複雜的（太深）。
例如：
- 電商系統 → 「使用者下訂單」
- SaaS → 「使用者登入並看到 Dashboard」
- API 服務 → 「收到 webhook 並處理」
2.2 從入口往內追
路由定義 → Controller → Service → Repository → Database
↓ ↓ ↓ ↓
URL 對應 驗證/轉換 商業邏輯 資料存取
追蹤的方法：
- 找路由定義 — 搜尋 URL path（如
/api/orders） - 找 controller — 這個 endpoint 呼叫了什麼 function
- 往下追 — 這個 function 又呼叫了什麼、用了哪些 model
- 標記 — 在你覺得重要的地方加書籤或註解
用 IDE 的「跳到定義」和「查找引用」功能大量使用。
2.3 搭配測試來理解
# 如果有測試，測試是最好的文件
# 看測試檔可以知道：
# - 這個 function 的預期輸入輸出是什麼
# - 邊界條件有哪些
# - 業務規則是什麼
grep -r "describe\|it(" tests/orders/測試是「可執行的文件」。 如果有測試，先看測試再看實作。
2.4 更新架構圖
經過 Day 2，你的架構圖應該更豐富了：
[使用者] → [前端 Next.js]
│
├→ POST /api/orders → [OrderController]
│ ├→ [AuthMiddleware] 驗證 JWT
│ ├→ [OrderService] 計算金額、檢查庫存
│ │ ├→ [ProductRepo] 查商品
│ │ └→ [InventoryRepo] 扣庫存
│ └→ [PaymentService] 呼叫 Stripe
│
└→ GET /api/orders → [OrderController]
└→ [OrderRepo] 查詢 + 分頁
Day 3：擴展理解 + 記錄盲點
目標：理解 2-3 條路徑，能自信地做小型改動。
3.1 追蹤更多路徑
選另外 1-2 個重要功能，重複 Day 2 的流程。通常第二條路徑會快很多，因為你已經理解了基本結構。
3.2 識別「地雷區」
每個 codebase 都有：
| 類型 | 特徵 | 怎麼辨認 |
|---|---|---|
| God Class | 一個檔案 2000+ 行 | wc -l 排序 |
| 無人敢動區 | git log 顯示很久沒改、或只有特定人改 | git log --format='%an' <file> |
| 高 churn 區 | 經常被修改，代表不穩定或設計不好 | `git log —oneline |
| workaround 集中地 | 註解裡有 TODO、HACK、FIXME | grep -r "TODO|HACK|FIXME" src/ |
3.3 記錄你的發現
寫一份筆記（給自己，也給未來的新人）：
# Codebase 筆記
## 架構概覽
[你畫的架構圖]
## 核心流程
1. 下訂單：OrderController → OrderService → Stripe
2. 登入：AuthController → JWT 生成 → Redis 存 session
## 關鍵檔案
- `src/services/order.ts` — 訂單商業邏輯核心
- `src/middleware/auth.ts` — 認證邏輯
- `config/database.ts` — 資料庫連線設定
## 地雷區
- `src/utils/legacy.ts` — 2000 行，沒有測試，別碰
- `src/services/billing.ts` — 有 3 個 TODO 說要重構
## 還不懂的
- [ ] Cache invalidation 策略是什麼？
- [ ] WebSocket 是怎麼處理的？
- [ ] 為什麼 User model 有兩個 email 欄位？AI 在這裡能幫你什麼
AI 可以大幅加速 Day 1-3 的過程：
| 任務 | 怎麼用 AI |
|---|---|
| 理解目錄結構 | 「這個專案的架構是什麼？主要的 entry point 在哪？」 |
| 理解某個 function | 「這個 function 做了什麼？輸入輸出是什麼？」 |
| 追蹤呼叫鏈 | 「當使用者呼叫 POST /api/orders 時，request 經過哪些 function？」 |
| 理解商業邏輯 | 「這段 if-else 的每個分支代表什麼商業情境？」 |
| 找相關檔案 | 「跟使用者認證相關的檔案有哪些？」 |
AI 不能幫你的：
- 判斷架構設計的「為什麼」（需要問原作者或看 ADR）
- 理解不在 code 裡的商業規則
- 判斷哪些地方是地雷（需要結合 git history 和經驗）
正確的使用方式： 用 AI 加速資訊收集，但自己做判斷和整合。不要盲信 AI 對 code 的解讀——它可能漏掉 side effect 或誤解商業邏輯。
常見的錯誤做法
| 錯誤 | 為什麼不好 | 應該怎麼做 |
|---|---|---|
| 從第一行開始逐行讀 | 沒有全景，不知道什麼重要 | 先看結構，再看細節 |
| 試圖一次理解所有東西 | 不可能，會資訊過載 | 一次只追一條路徑 |
| 只看 code 不跑起來 | code 的行為可能跟你想的不一樣 | Day 1 一定要把系統跑起來 |
| 不敢問問題 | 最快的文件是人 | 記下問題，集中問原作者 |
| 不做筆記 | 三天後你會忘記 Day 1 的發現 | 邊探索邊記錄 |
反思問題
- 你上次接手一個新專案，花了多久才能自信地做改動？ 有沒有可能更快？
- 你有離職/交接文件的習慣嗎？ 你留給下一個人的 codebase 好理解嗎？
- 你用 AI 探索 codebase 的效率如何？ 你知道該問什麼問題嗎？
- 你能在 10 分鐘內畫出你目前專案的架構圖嗎？ 如果不能，你可能還不夠理解它。
延伸閱讀
- Debug 方法論 — Debug 也是一種理解 codebase 的方式
- 系統分析與設計 — SA 的五層思維框架也適用於理解現有系統
- Code Review 方法論 — Review 別人的 code 是持續理解 codebase 的方式
- 技術債管理 — 理解 codebase 時你會發現很多技術債