用 CodeGraph 節省 Token（入門筆記）

整理 CodeGraph 入門筆記。

前言

我在使用 AI 工具時常有這樣的操作：每當增加或修改了軟體專案的某個功能或設計決策，會讓 AI agent 更新相關的開發文件，如架構文件、設計文件等（有時候 agent 會自動更新文件）。

當我知道有個叫做 CodeGraph 的工具，能夠建立軟體專案的程式碼圖譜，用來回答專案的各種問題和查詢，進而節省 token，我就想立刻試試看。同時也好奇：若在專案中使用了 CodeGraph，那我原先讓 AI agent 幫我維護的開發文件，還有必要繼續更新嗎？兩者似乎有重疊之處。

Fun fact：CodeGraph 在 GitHub 平台上的星星數從今年（2026）五月底開始暴漲。

CodeGraph 的學習資源，首推官方文件。在這篇筆記中，主要是以 Q & A 的形式來回答我在入門上手時的一些疑問，包括：

• Q1: CodeGraph 對開發者有什麼用處？
• Q2: CodeGraph 支援哪些程式語言？
• Q3: CodeGraph 能夠回答什麼、不能回答什麼？
• Q4: CodeGraph 是如何運作的？
• Q5: 如何在本機安裝並開始建立軟體專案的圖譜？
• Q6: 其他注意事項？

有些內容是先用 AI 生成，我再進行裁減和修訂。若要節省時間，可以看每一節的標題以及用黃色標示的重點文字。

Q1: CodeGraph 對開發者有什麼用處？

簡單來說：省 token，也就是省錢。

CodeGraph 對開發者的核心用處在於提升 AI agents（如 Claude Code、Cursor 等）的效率，同時提供開發者一個強大且零設定的本地端程式碼探索工具。

以下展開說明 CodeGraph 為開發者帶來的幾項好處：

1. 讓 AI 開發助手變得更快、更精準且更省錢 

當開發者使用 AI 代理程式探索程式碼庫時，AI 通常會將大量資源消耗在「發現」階段（例如盲目使用 grep 或逐一讀取檔案來尋找關聯）。CodeGraph 預先建構了知識圖譜，讓 AI 能在單次呼叫中直接取得所需的確切程式碼與結構關係，無須掃描檔案。這能帶來顯著的效能提升：

• 減少 58% 的工具呼叫次數。
• 處理速度提升 22%，且檔案讀取次數幾乎降至零。
• 在大型、複雜的專案中，這種精準度能為開發者省下大量 API Token 的成本。

👉 官方文件：Introduction > Why it matters

2. 最佳化 CI（持續整合）流程中的測試執行

開發者可以將 CodeGraph 整合到 CI 流程中。透過 codegraph affected 指令，系統能追蹤依賴關係的傳遞路徑，精準找出哪些測試檔案受到此次程式碼變更的影響。這讓 CI 系統只需要執行相關的測試，而不必跑遍所有測試，大幅節省時間與運算資源。

👉 官方文件：Affected Tests in CI

3. 快速釐清專案架構與影響範圍（Impact Analysis）

對於開發者自身而言，CodeGraph 也是極佳的架構分析工具。開發者可以透過命令列（CLI）或自然語言探索程式碼：

• 影響範圍計算：在修改程式碼前，計算該變更會牽連到的「傳遞半徑（transitive radius）」。
• 追蹤呼叫路徑（Callers/Callees）：一步步走訪並釐清函式之間的呼叫網路。
• 探索模式（Explore）：透過自然語言提問，系統會一次性回傳多個相關符號的原始碼及其呼叫路徑。

👉 官方文件：The Knowledge Graph > Querying it

4. 自動解析網頁框架的 URL 路由 

在開發 Web 應用程式時，尋找 API 路由與對應程式碼的綁定往往很花時間。CodeGraph 能夠自動識別多種主流框架（如 Django、Express、FastAPI、React Router 等）的路由檔案。它會自動建立路由節點與處理常式（handler）之間的連結，當開發者或 AI 查詢某個控制器（controller）或視圖（view）時，就能直接得知綁定該程式的具體 URL 模式。

👉 官方文件：Resolution & Frameworks

5. 零維護負擔且 100% 保障隱私

• 全自動背景同步：內建的檔案監控器（File watcher）會捕捉每一次的檔案編輯並進行去抖動處理（debounced auto-sync），確保圖譜隨時保持最新狀態，開發者幾乎不需要手動重新整理索引。
• 完全本地端運行：所有的資料提取與儲存（SQLite）都發生在開發者的本地 .codegraph/ 目錄中，無須提供 API 金鑰，程式碼資料也絕對不會離開本地電腦，確保企業與個人專案的最高安全性。

Q2: CodeGraph 支援哪些程式語言？

👉 官方文件：Languages

Q3: CodeGraph 能夠回答什麼、不能回答什麼？

CodeGraph 是一個透過解析抽象語法樹（AST）來建立本地知識圖譜的工具，因此它很擅長回答客觀的結構性問題（structural questions），但無法直接回答主觀的意圖或純動態的執行期行為。

CodeGraph 能夠協助回答的問題包括：

• 程式碼結構與依賴關係： 它可以精準回答符號（如函式、類別、介面等）之間的關聯。例如誰呼叫了特定函式（callers/callees）、誰繼承或實作了某個介面（extends/implements），或是檔案之間的匯入與匯出網絡。
• 探索端到端（End-to-End）的呼叫路徑： 它支援接受自然語言查詢（例如：「驗證中介軟體如何連接到使用者模型？」），並在單次查詢中回傳相關原始碼與這些符號之間的完整呼叫路徑。
• 框架與路由的綁定對應： 若查詢特定的視圖（view）或控制器（controller），它能直接找出並回答綁定該處理常式的具體 URL 路由模式。
• 變更的影響範圍（Impact Analysis）： 它可以計算修改某段程式碼後會牽連到的傳遞半徑（transitive radius），甚至能協助 CI 系統精確找出哪些測試檔案受到此次變更的影響。

CodeGraph 不能直接回答的問題包含：

• 架構設計的「決策原因」與「商業意圖」： 例如架構設計決策。CodeGraph 無法告訴你「為什麼當初這樣設計」或「這段程式碼的商業邏輯目的」。這是因為圖譜中的資料完全是從 AST 中提取出來的確定性結果，絕對沒有經過任何 LLM 的摘要或主觀推測。它只記錄程式碼「長什麼樣子」，不記錄「為什麼」。
• 純粹的執行期（Runtime）動態行為： 靜態解析本質上無法捕捉依賴動態計算或間接呼叫的流程。雖然 CodeGraph 會透過特定的合成器（synthesizers）盡力橋接常見的動態分派邊界（例如 React 重新渲染、觀察者模式或回呼註冊等），但高度動態的執行期結果仍無法單靠圖譜解答。

也就是說，在「架構設計決策」的部分， CodeGraph 無法直接幫你做架構決策或解釋設計理念。然而，當你將 CodeGraph 提供給 AI 代理程式（如 Claude Code 或 Cursor）使用時，它能幫助 AI 瞬間掌握現有的專案架構全貌、準確的呼叫圖與依賴關係，免去 AI 盲目掃描與搜尋檔案的時間。在此基礎上，AI 就能夠基於 CodeGraph 提供的客觀結構事實，進一步跟你討論並協助你做出高品質的架構重構或設計決策。

Q4: CodeGraph 是如何運作的？

• 程式碼解析與本地儲存：它使用 tree-sitter 來解析你的程式碼，並將所有的符號（symbols）、邊緣（edges）以及檔案結構存儲於本地的 SQLite 資料庫中（位於 .codegraph/ 目錄）。它保證 100% 本地運行，無須 API 金鑰，資料也絕不會離開你的電腦。
• 確定性的知識圖譜：它會構建出一個包含符號（如函式、類別、方法等）、邊緣（如呼叫、匯入、繼承等關係）以及檔案（支援全文搜尋）的知識圖譜。這些資料的擷取完全是基於抽象語法樹（AST）的確定性結果，而不是依賴 LLM 的摘要。
• 多元存取管道：建構好的知識圖譜可以透過模型上下文協定（MCP）、命令列介面（CLI）或 TypeScript 函式庫來進進行查詢。

Q5: 如何在本機安裝並開始建立軟體專案的圖譜？

可按照以下步驟快速體驗：

1. 安裝 CodeGraph CLI

• 如果機器上已經安裝了 Node.js，可直接在終端機輸入以下指令來安裝：
  
  npm i -g @colbymchenry/codegraph
  
  
• CodeGraph 安裝好之後，應該會自動將 codegraph 加入系統的 PATH 環境變數中。安裝完成後，請開啟新的終端機視窗再進行後續步驟。

CodeGraph CLI 是核心引擎，一定要安裝。

2. 連接 AI agents（自動設定）

安裝過程中會自動偵測並設定本機目前有安裝的 AI agents（例如 Claude Code、Cursor、Hermes Agent、Gemini CLI 等），並將 CodeGraph 的 MCP 伺服器連接至這些工具中。此步驟僅負責連接工具，還不會對任何程式碼進行索引。

如果將來需要再次設定 AI agents，也可以手動執行以下命令（任何目錄）：

codegraph install 

它會自動偵測目前環境有安裝哪些 agents 並自動勾選。如下圖：

上圖只是整個安裝設定過程的第一個問題。按 Enter 之後，還有其他問題要回答。下圖是安裝完成的畫面：

如果你是在 VS Code 中使用 AI agent 套件，只要該套件支援自訂 MCP 伺服器，就會由安裝程式自動設定好（不需要手動設定 MCP）。參考下圖，是 VS Code 中的 Codex 的 MCP 伺服器設定：

3. 初始化並建立第一個圖譜

在你的專案的根目錄下執行命令：

codegraph init

此命令會在你的專案中建立本地的 .codegraph/ 目錄，並建構完整的程式碼圖譜。

下圖展示的是我在 VS Code 的終端機視窗裡面下指令來初始化某個專案的程式碼圖譜：

圖譜建立後，CodeGraph 會透過系統原生的檔案監控（File watcher）來捕捉每一次的檔案變更，並自動進行增量同步（Auto-sync），因此往後幾乎不需要再手動重新建構圖譜。

4. 驗證與提問

你可以在專案目錄下執行 codegraph status 來進行快速檢查，該指令會回報圖譜中成功解析的節點（node）、邊緣（edge）和檔案數量，以及活躍的 SQLite 後端狀態，確認索引已準備就緒。

只要在專案目錄下有用 codegraph init 命令建立 .codegraph/，你的 AI agent 就會在需要時自動使用 CodeGraph 的內建工具來探索程式碼，完全不需要額外設定。

下圖展示的是我在 VS Code 中使用 Codex 來提問的過程：

如果偏好 CLI 下指令的方式，可參考官方文件：CLI。

Q6: 其他注意事項？

預設情況下，CodeGraph 會嚴格按照專案的 Git 設定來判斷哪些是真正屬於專案的程式碼（加入圖譜），以及哪些檔案或目錄要忽略（不加入圖譜）。如果有例外的情形，則可以透過 codegraph.json 檔案來調整預設行為。

詳情可參閱官方文件：Configuration

注意：如果你修改了專案根目錄下的 codegraph.json 設定檔，這些變更並不會由內建的檔案監控機制自動同步套用。因此，如果有做以下任何設定變更，都必須手動重新建立索引：

• 排除特定已追蹤目錄（修改 exclude 陣列）。
• 設定自訂的檔案副檔名（修改語言映射）。
• 納入被 Git 忽略的嵌套子專案（修改 includeIgnored 陣列）。

在完成上述任一修改後，必須在終端機手動執行 codegraph index 指令，這樣系統才會根據新的設定檔規則重新建立圖譜。

結語

我用 CodeGraph 的目的很單純，就是想節省 token 用量。從 Codex 的回應結果來看，應該多少有些幫助。之後如果有更多使用心得，再來補充。

Keep learning!