Vincent5588 Wiki

陌生 Codebase 探索 SOP

閱讀時間約 4 分鐘

陌生 Codebase 探索 SOP

不熟悉的 codebase 上直接 vibe code 是高風險行為——你無法判斷 AI 的決策是否合理，也無法在它走錯時及時拉回。動工前先做四步建立心智圖。

為什麼陌生 codebase 不能直接 vibe

  • AI 可能正確理解局部，但錯估全域 invariants（譬如「這個 service 不能直接寫 DB，要走 repository」）
  • 你無法 sanity-check AI 的決策（譬如「為什麼它把 logic 放這檔？」）
  • 走錯時你沒能力察覺——直到 PR review 才被發現

→ Vibe coding 的前提是「你在這個 codebase 有 mental model 能驗收 AI 產出」。

四步流程

Step 1：問場域

問 Claude（或 Sub-agent）：

  • 「告訴我這個 codebase 中哪裡處理 auth？」
  • 「哪個檔案負責 X？」
  • 「主要 framework / library 有哪些？」

目的：先把 module boundaries 摸清楚。

Step 2：找類似功能

問：

  • 「告訴我跟 X 類似的功能有哪些？列出檔案名與 class 名。」
  • 「過去類似需求是怎麼實作的？」

目的：找 reference implementation，後續 prompt 可指定「請參考 xxx.ts 的寫法」。

Step 3：建立心智圖

根據以上資訊自己讀關鍵檔案，建立架構心智圖：

  • 主要 module / package 的職責
  • 跨 module 的依賴方向
  • 共用 utility / type / convention
  • DB schema / API 規格

這步不能完全靠 AI——必須自己讀過，否則 vibe coding 時無法 sanity-check。

Step 4：才開始寫功能

此時才進入 Plan-then-Execute SOP Step 3「計畫產出」。

跟 Plan-then-Execute SOP 的關係

陌生 codebase 場景下，把 SOP step 2「Codebase 探索」展開成 4 個子步驟：

Plan-then-Execute Step 2 (Codebase 探索)
  ↓ (陌生 codebase 場景)
  ├── 子 step 1: 問場域
  ├── 子 step 2: 找類似功能
  ├── 子 step 3: 建立心智圖（自己讀！）
  └── 子 step 4: 才開始寫
       ↓
       回到 Plan-then-Execute Step 3 (計畫產出)

熟悉的 codebase 可以跳過子 step 1-3，直接進入 step 4。

適用情境

  • 新接手一份遺留 codebase
  • 跨團隊借用其他組的 module
  • 第一次處理某個 framework / 第三方 library 的整合
  • 大重構前的場域盤點

不適用情境

  • 自己長期維護的 codebase（可以跳過）
  • 一次性 leaf script（可考慮直接寫，失敗成本低）
  • 純 utility 補強（譬如新增一個 string helper）

落地工具

工具角色
Sub-agent派一個 sub-agent 做 Step 1-2，主對話保持乾淨
Skills 九種類型 / Codebase Onboarding Engineer 類專屬 skill專門用於 codebase 探索的 skill（自訂；可參考 IT vault 的 Explore agent 設計）
CLAUDE.md 4 層機制把已建立的心智圖寫進 CLAUDE.md，給未來自己 / 同事用
Tree of Code 工具（譬如 ast-grep）Step 1 找 module 邊界

違反時的常見症狀

  • 「我以為 vibe 一下就好，結果 AI 改了 5 個我不熟的檔，全壞」→ 跳過 Step 1-3
  • 「AI 重新發明已有的 utility」→ 沒做 Step 2「找類似功能」
  • 「PR review 才發現 AI 把 logic 放錯 layer」→ 自己沒讀過 codebase 沒能力即時拉回

相關

關係圖譜

反向連結