用 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 的成本。
2. 最佳化 CI（持續整合）流程中的測試執行
開發者可以將 CodeGraph 整合到 CI 流程中。透過 codegraph affected 指令，系統能追蹤依賴關係的傳遞路徑，精準找出哪些測試檔案受到此次程式碼變更的影響。這讓 CI 系統只需要執行相關的測試，而不必跑遍所有測試，大幅節省時間與運算資源。
👉 官方文件：Affected Tests in CI
3. 快速釐清專案架構與影響範圍（Impact Analysis）
對於開發者自身而言，CodeGraph 也是極佳的架構分析工具。開發者可以透過命令列（CLI）或自然語言探索程式碼：
- 影響範圍計算：在修改程式碼前，計算該變更會牽連到的「傳遞半徑（transitive radius）」。
- 追蹤呼叫路徑（Callers/Callees）：一步步走訪並釐清函式之間的呼叫網路。
- 探索模式（Explore）：透過自然語言提問，系統會一次性回傳多個相關符號的原始碼及其呼叫路徑。
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 支援哪些程式語言？
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 
上圖只是整個安裝設定過程的第一個問題。按 Enter 之後，還有其他問題要回答。下圖是安裝完成的畫面：
如果你是在 VS Code 中使用 AI agent 套件，只要該套件支援自訂 MCP 伺服器，就會由安裝程式自動設定好（不需要手動設定 MCP）。參考下圖，是 VS Code 中的 Codex 的 MCP 伺服器設定：
3. 初始化並建立第一個圖譜
codegraph init
此命令會在你的專案中建立本地的
.codegraph/ 目錄，並建構完整的程式碼圖譜。
4. 驗證與提問
你可以在專案目錄下執行codegraph status 來進行快速檢查，該指令會回報圖譜中成功解析的節點（node）、邊緣（edge）和檔案數量，以及活躍的 SQLite 後端狀態，確認索引已準備就緒。
Q6: 其他注意事項？
- 排除特定已追蹤目錄（修改
exclude陣列）。 - 設定自訂的檔案副檔名（修改語言映射）。
- 納入被 Git 忽略的嵌套子專案（修改
includeIgnored陣列）。