實戰背景

你第一天加入新團隊,前輩丟了一個 repo 連結給你:「這是我們的訂單系統,先把環境跑起來,下午跟你講第一個任務」。

這個 repo 有兩百多個檔案,分散在 apps/、libs/、services/、packages/ 各種目錄。你大可花一個早上點開每個資料夾找入口、翻 README、用 IDE 跑搜尋,但這樣做很慢,而且容易抓錯重點。

CM 的 get_architecture 工具能替你把整個 repo 濃縮成一份高階總覽,讓你在十秒內抓到心智模型。這份心智模型會決定你接下來怎麼看 code,值得每次 onboarding 都先跑一遍。

步驟一：先確定圖譜是最新的

如果你接手的是別人已經建過圖譜的 repo,先確認索引還新鮮:

codebase-memory-mcp index

index 是冪等的,已建過就只補差異,不會重頭跑。

步驟二：要一份架構總覽

get_architecture 預設只回 overview(node/edge 數、語言、package、入口)。想一次拿到結構與熱點,可以用 aspects 參數指定面向。

可選的面向包含:overview、structure、dependencies、hotspots、entry_points、boundaries、layers 等。第一次 onboarding 至少要 overview 加 hotspots,後者告訴你哪些檔案連結最多、最常被改動。

── 跟 AI 對話 ──

• You:

  我剛接手這個 repo,給我一份架構總覽,我要看主要模組、入口點和 hotspots。

• AI:

  我呼叫 get_architecture 並指定 aspects: ["overview", "hotspots"],一次拿到摘要與熱點清單。

  CM 呼叫: get_architecture() CM 回傳(摘要):

  {
    "overview": {
      "nodes": 1842,
      "edges": 3107,
      "languages": ["TypeScript", "JavaScript", "SQL"],
      "packages": ["apps/api", "apps/web", "libs/orders", "libs/billing", "libs/shared"],
      "entry_points": ["apps/api/src/main.ts", "apps/web/src/index.tsx"]
    }
  }

  分析： 專案有 1842 個符號、3107 條邊,主要語言是 TypeScript。五個 package 分別是 API、Web、訂單、計費、共用層。兩個入口點:apps/api/src/main.ts(後端)與 apps/web/src/index.tsx(前端)。

步驟三：解讀 overview

── 五個關鍵欄位 ──

從這份 overview 你已經知道:這是一個前後端分離的 TypeScript monorepo,後端入口在 apps/api/src/main.ts。比直接點資料夾快得多。

步驟四：聚焦到單一模組

overview 太廣,想看 libs/orders 這個核心業務模組,可以把範圍縮到該路徑:

• You:

  只看 libs/orders 這個模組的架構。

• AI:

  我把範圍指定到 libs/orders。

  CM 呼叫: get_architecture(path: "libs/orders") CM 回傳(摘要):

  入口: libs/orders/src/index.ts (匯出 OrderService、OrderRepository)
  核心類別: OrderService (in: 12, out: 8)
  核心類別: OrderRepository (in: 9, out: 3)
  hotspots: OrderService.create (被 12 個地方呼叫)

  分析： OrderService 是這個模組的中心,被 12 個地方呼叫,對外依賴 8 個符號。OrderService.create 是單一最大熱點,你要改訂單流程,幾乎一定會碰到它。

步驟五：建立心智模型

把上面幾步的資訊組起來,你的心智模型大概是這樣:

[apps/web] (前端入口)
    │ 呼叫
    ▼
[apps/api/src/main.ts] (後端入口)
    │ 載入
    ▼
[libs/orders] ── OrderService.create (hotspot, 12 個呼叫者)
    │ 依賴
    ▼
[libs/billing] (計費)
[libs/shared] (共用工具)

這份草圖讓你之後看 code 時有方向:從 main.ts 順著呼叫鏈往下游走,先認識 OrderService.create,再往下到 billing。比起漫無目的地點開檔案,效率天差地別。

什麼時候不該只用總覽?

get_architecture 是地圖,不是實地。下列情況要再往下挖:

• 要改動 hotspot:OrderService.create 被很多人呼叫,動它之前先跑一次 trace_path(見範例 010)看完整影響面。
• 跨服務行為:圖譜只看靜態呼叫關係,執行期的訊息佇列、外部 API 不一定看得到。
• 效能問題:hotspot 不等於效能瓶頸,要再搭配 profiler。

總覽是入口,真正的細節還是要回到個別符號的原始碼。

關鍵學習點

• get_architecture 是 onboarding 起手式:十秒內拿到模組清單、入口點、熱點,勝過一個早上點資料夾。
• 用 path 縮範圍:overview 太廣時,指定單一模組路徑可以聚焦到該層的入口與核心類別。
• 邊 / 節點比代表耦合度:比偏高代表改一處會牽動很多地方,做變更前要先跑影響分析。
• 總覽不是實地:它給方向,但跨服務行為、執行期細節、效能瓶頸要靠其他工具補上(trace_path、profiler、執行 log)。