CodeGraph 是替 AI 程式開發助手準備程式碼地圖的開源工具，它先把函式、類別、呼叫與相依關係建立成可查詢的圖譜，再讓 Agent 取得相關原始碼，減少每次接手問題時重新搜尋檔案的工作。
它值得關注的地方，是讓檢索更有結構，本文整理它的原理、安裝方式，以及如何判斷這張地圖對自己的專案有沒有幫助。
內容目錄
CodeGraph 是什麼？先認清專案與用途
本文介紹的是 colbymchenry/codegraph，npm 套件名稱為 @colbymchenry/codegraph，不要只憑 CodeGraph 名稱安裝同名工具。
官方網站將它定位為本地優先的程式碼分析工具，可透過 MCP 接到既有 AI 開發助手。它提供的是結構化檢索能力，不是另一個語言模型，也不會替原本的模型權重增加知識。
程式碼地圖如何建立？從檔案變成節點與關係
依官方原理文件，CodeGraph 使用 Tree-sitter 解析原始碼，抽出函式、類別、方法等節點，再整理呼叫、匯入與繼承等關係。資料存放在專案內的 SQLite 資料庫 .codegraph/codegraph.db，並提供全文搜尋。
你可以把它想成接手陌生城市時先拿到路網圖。搜尋關鍵字能找到某個地點，圖譜則幫助追問它和其他地方怎麼相連。例如登入 API 經過哪個驗證函式，或修改共用模組可能碰到哪些呼叫端。
知識圖譜文件也區分直接從語法抽出的關係，以及動態邊界上由規則補出的關係，後者會標記為 heuristic，也就是啟發式推導此，圖譜適合協助找線索，不能當成所有執行期行為都已完整證明。
如果你看過站上的Graphify 知識圖譜整理，可以把兩者當作相關但不同的專案閱讀，套件名稱、支援資料與建立圖譜的方法不能直接互套。
「提升 17 倍」該怎麼看？先把指標拆開
目前公開測試測的是 Agent 回答程式架構問題時，花了多少工具呼叫、時間、Token 與費用，沒有測量通用智力。以 專案 README 的 VS Code 測試為例，使用與未使用 CodeGraph 的結果如下。
| 指標 | 未使用 CodeGraph | 使用 CodeGraph | 依原始值計算 |
|---|---|---|---|
| 工具呼叫 | 28 次 | 2 次 | 減少約 92.9% |
| 耗時 | 130 秒 | 58 秒 | 減少約 55.4% |
這組 README 測試使用 Claude Opus 4.8，每個開源專案設定一題架構問題，各組跑四次取中位數。對照組阻擋透過命令列偷用 CodeGraph，以免比較失真。它適合說明查找成本可能下降，不能延伸成修復成功率、程式品質或所有開發工作的加速比。
少處理 Token，不一定留下更小的上下文
另一個容易混淆的地方，是累積處理量和對話裡仍然保留多少內容。專案的多回合上下文測試指出，CodeGraph 一次回傳較完整的來源內容，可能減少反覆查找，卻留下更多檢索內容在上下文中。這份測試的模型與回合數，也和 README 的單題測試不同，數字不能混在一起算。
所以我會分別看總 Token、費用、等待時間，以及後續對話還剩多少空間。若 Agent 一次拿回很多無關程式，即使工具呼叫很少，也不一定是理想結果。
安裝分三步：CLI、連接助手、建立專案索引
依官方快速開始，安裝指令列工具和建立專案圖譜是不同步驟。以下採已有 Node.js 與 npm 的路線，固定版本方便對照。未安裝 Node.js 的環境，官網另提供內含執行環境的獨立版本。
npm install -g @colbymchenry/[email protected]
codegraph version
codegraph installcodegraph install 會依你選擇的助手寫入 MCP 設定，並可能加入專案指引或工具權限設定。執行時確認套用到全域還是目前專案，完成後重新啟動對應助手。這一步還沒有替專案建立索引。
接著進入要分析的專案。your-project 要替換成自己的目錄，init 會建立本地 .codegraph/ 並完成首次索引。本文沒有在你的電腦安裝 CodeGraph，也未執行這組效能測試。
cd your-project
codegraph init
codegraph status先確認狀態有列出合理的檔案、節點與關係數，再讓助手查詢。如果數量明顯偏少，先查語言支援、排除規則與專案根目錄，別直接假定整個程式庫都已完整收錄。
三種查詢，用在不同階段
CLI 文件把搜尋符號、整體探索與影響分析分開。下面是操作示例，AuthService 只是占位名稱，需換成專案實際存在的符號。
codegraph query "AuthService"
codegraph explore "Trace login from route to session creation"
codegraph impact "AuthService" --depth 3- 找位置：先用 query 確認符號與定義，不必立刻讀完整個資料夾。
- 懂流程：用 explore 取得相關原始碼與路徑，再核對入口、呼叫端及設定。
- 準備修改：用 impact 找出可能受影響的範圍，再決定需要檢查哪些檔案與測試。
我會要求 Agent 先回傳來源檔案、相關符號，以及哪些連線是推導結果，再提出修改計畫。影響分析能幫忙選擇檢查範圍，不能代替執行測試。程式碼的安全性則是另一道工作，可延伸閱讀Security Guidance 的修改與審查流程。
程式改了會自動更新，但仍要查看索引狀態
官方索引指南說明，當助手啟動 MCP 伺服器後，檔案監看會把變更整理成增量更新。
寫入檔案與完成同步之間仍有短暫空窗，回應可能標出尚待同步的檔案，這時應讀取該檔的目前內容。
若監看被停用，或在助手工作階段之外跑自己的腳本，可依需要先同步再查詢。批次修改後也可以用狀態確認進度，不必每次都強制重建整張圖。
codegraph sync
codegraph status排除目錄、.gitignore、支援的副檔名與檔案大小限制，都會影響收錄範圍。自動更新是維護機制，不代表所有設定、動態載入與外部服務都已被理解。
本地優先不等於整套 AI 工作都離線
CodeGraph 的圖譜解析與資料庫在本機，但若開發助手呼叫雲端模型，回傳給助手的程式碼片段仍可能進入模型請求。這是根據工具資料流所做的判斷，不能只因索引存在本地，就宣稱整套工作完全不會外送程式碼。
專案遙測文件另列有匿名使用統計，包含工具名稱、語言、平台及彙總次數。依文件，它不收原始碼、路徑、符號名稱或查詢內容。這和 AI 助手把哪些內容傳給模型，是兩件不同的事。
不想參與遙測時，可使用下列設定。DO_NOT_TRACK=1 也會關閉背景更新檢查，專案文件對兩者有分別說明。
codegraph telemetry off什麼情況值得試？先用自己的問題驗收
常接手陌生專案、需要追跨檔案流程，或修改共用模組前要找影響範圍的人，較容易看出這類工具的價值。
若只是小型腳本或已知道錯誤在哪一行，原本的搜尋與閱讀可能已足夠，還要把首次索引和維護成本算進去。
我的建議是挑一個已知答案的架構問題，以及一個真實修改需求。對照使用前後的來源準確度、呼叫次數、等待時間、費用與測試結果。
只有找得快、沒有找得對，還不足以導入日常流程。
圖譜之外，設計決策、部署限制與團隊慣例也應另行保存，站上的OpenWiki 專案知識整理可作為文件層的延伸閱讀。程式結構索引和文字知識各自維護，會比把所有資訊都當成一張圖更容易檢查。
CodeGraph 常見問題
CodeGraph 安裝好就會自動分析所有專案嗎？
不會。安裝 CLI、設定助手的 MCP，以及在每個專案執行 codegraph init 是不同步驟。應先用 status 確認索引狀態。
CodeGraph 是完全離線的嗎？
本地解析與圖譜資料庫不代表整套 AI 工作離線。雲端助手可能把查回的程式碼交給模型，遙測則是另一項可關閉的設定。
修改程式後需要重新建立圖譜嗎？
正常 MCP 工作階段可透過監看增量同步。遇到監看停用、同步提示或腳本使用情境時，應確認狀態，必要時執行 codegraph sync。