背景

你接手了一個陌生 codebase（例如 open source repo、新工作的 legacy project）。傳統做法：

1. 看 README（不一定準）
2. grep 關鍵字（看到一堆無關結果）
3. 讀十個檔才找到入口（耗時）

graphify 提供更快的路徑：把整個 codebase 建成 JSON 圖譜後，直接問核心問題，graphify 會 BFS 出子圖給你。

適用情境

• 第一次 clone open source repo 想貢獻
• 新工作的 onboarding
• 需在短時間內回答架構問題（code review、面試、bug 調查）

完整流程

步驟 1：clone 並 install

git clone https://github.com/tiangolo/fastapi
cd fastapi

uv tool install graphifyy
graphify claude install --project

步驟 2：全量 AST build（不需 API key）

graphify extract . --code-only

💡 FastAPI corpus 大量程式碼、少 docs，--code-only 可完全跳過 LLM，30 秒建完。

步驟 3：看 god node 找核心入口

head -50 graphify-out/GRAPH_REPORT.md

預期看到：

• 🌟 God nodes：連結數最高的節點，通常是核心類別（例如 APIRouter、FastAPI、Request）
• 🎨 Communities：Leiden 演算法分出的子系統（例如 routing、dependency injection、security）

god node 告訴你「往哪看」——「這個 codebase 的核心是 APIRouter」

步驟 4：用路徑找兩個概念的連結

graphify path "FastAPI" "ModelField"

graphify 回傳最短路徑：

Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder
  DefaultPlaceholder <--references-- get_request_handler()
  get_request_handler() --references--> ModelField

→ 你立刻理解 FastAPI 的 model validation 是如何傳導到 request handler 的。

步驟 5：用 explain 認識神祕術語

graphify explain "Dependant"

回傳該節點的所有 in/out 連結 + 社群。你看到它呼叫 47 個節點，屬於 Community 2（dependency injection），就能猜出它的角色。

步驟 6：自然語言問問題

graphify query "authentication 是怎麼實作的？"

graphify 回傳子圖（5-8 個相關節點 + 邊），助理基於此回答你最深入的部分。

對比傳統做法

graphify 對 FastAPI 級 codebase 通常可省 50-80% exploration 時間。¹

後續維護

把 graphify-out/ commit 進你的 fork：

graphify hook install        # 自動重建
git add graphify-out/
git commit -m "chore: init graphify graph"

下次你或你要帶上手的人 clone 後，助理直接讀 GRAPH_REPORT.md 而不用重新建圖。

失敗處理

內部連結

• graphify build 指令詳解
• graphify path-explain 指令詳解
• 快速入門工作流

下一步

1. 大型 monorepo 重購範例
2. PR 圖譜審查 + 團隊共享 graphify-out