Graft 評測：把程式碼圖譜寫成 markdown 檔案，塞進 Claude Code 的上下文層

Graft 想解決的是 agent 每次任務都重新認識一次 repo

README 把問題講得很直接：agent 每接一個任務就從零開始探索，grep 一個詞、開一個檔案、追一條 import、退回原點再試一次。它把這形容成「人類只 onboarding 一次，agent 每一次都 onboarding」。這個觀察不新，但 Graft 對它的歸因值得注意：它認為重複探索吃掉了一次執行裡大部分的 tool call、token 與延遲，而這些成本是純粹的 overhead，不產生任何修改。

它列出的三個性質是重複、丟棄、不共享。同一個任務再來一次要重付一次探索成本；agent 上一輪搞懂的東西隨著 session 結束消失；下一個同事和他的 agent 也從零開始。Graft 的目標讀者因此很明確：已經在用 Claude Code 之類工具、repo 規模大到探索階段明顯拖慢節奏的團隊。反過來說，小專案並不缺這個東西，agent 自己讀兩輪就摸清了，多一層圖譜只是多一份要維護的快取。

圖譜不是向量索引，是一疊可以 grep 的 markdown

這是我認為 Graft 最值得談的設計決定。README 明確寫著：no embeddings、no similarity search、no index to keep warm。圖譜就是一堆互相連結的檔案，agent 開啟它、grep 它、沿著連結走下去，跟讀 repo 裡其他檔案沒有兩樣。

每個節點是一份 markdown，對應一個系統、一個 API 或一個概念，用平實的英文說明這部分在做什麼、跟其餘部分怎麼連接，而不是傾倒一串函式名稱。README 強調這是「a real graph you can read」，並且說節點的內容是資深工程師會怎麼解釋這個系統的那種說明。

這個選擇的實際後果是雙面的。好處是沒有索引要保溫、沒有向量資料庫要跑、沒有服務要開著，整份圖譜是可攜的檔案，agent 用既有能力就能消費它。代價是檢索品質取決於 agent 沿著連結走的判斷力，而不是相似度分數；節點寫得含糊，agent 就會走錯分支。換句話說，Graft 把一部分檢索問題轉嫁給了圖譜本身的撰寫品質。

安裝只有兩行，但 graft init 會動 .claude/ 底下的檔案

Quick start 給的指令是：

npm install -g @nanonets/graft graft init

README 說 graft init 會問你要接上哪些 coding agent、從你的程式碼建出 graft/、並在 .claude/ 放進一個 statusline 與 hooks，所以從下一個 session 開始，Graft 會跟著 Claude Code 一起跑：把對應的節點拉進每個 prompt，並在每一輪之後於背景重建圖譜。文件說預設沒有 daemon、沒有需要記得的重新索引、沒有東西要跑或維護，圖譜就只是檔案。

這裡有幾個具體的開關值得記住。graft init --dry-run 會先列出它打算碰的每一個檔案，在你選定之前不會寫入任何東西。graft init --agents claude 可以跳過詢問，只接 Claude Code。不想裝全域的話 npx @nanonets/graft init 行為相同。另外 graft build 會自動把 graft/ 加進 .gitignore，因為圖譜被定位成本機、可重新產生的快取，像 node_modules 一樣不該進版控；團隊要共享的是 init 放進 .claude/ 的接線，所以 README 給的提交指令是 git add .claude && git commit -m "wire in graft"，其他成員各自跑 graft build 生成自己的圖譜。

值得注意的是，這個自動寫入 .gitignore 的行為是便利也是風險：如果你的 .gitignore 已經有複雜的規則或分層結構，最好先用 --dry-run 確認它插入的位置符合預期。

CLI 的其餘部分：grep、map、viz

README 的目錄列出幾個子命令。graft grep 與 graft map 歸在「Search & orient」之下，前者看起來是在圖譜上做搜尋，後者是取得整體方位。graft viz 負責視覺化。另外文件有專門一節談 monorepo 與多 repo 資料夾的處理。

我必須說清楚：這幾個子命令的具體旗標與輸出格式，在手上這份被截斷的 README 裡看不到。目錄只給了名稱與一句定位，沒有範例輸出。所以任何關於 grep 支援什麼語法、map 印出什麼結構、viz 產生靜態 HTML 還是開一個本機伺服器的描述，都不該由我補上。

能確定的是這些命令都繞著同一份 graft/ 目錄運作，而那份目錄是本地可重建的快取。這代表你可以放心刪掉它重跑，但也代表任何依賴它的自動化流程，都必須接受「這份資料可能隨時被重建」的前提。

官方 benchmark 的數字與它沒有回答的問題

README 開頭放了一張表，欄位是 Cold Claude Code 對上 Claude Code with graft：tool-call reduction +46%、token savings +42%、time savings +60%、correctness 從 54% 到 66%（+12 個百分點）。標題寫的是「Up to 4× cheaper and 3× faster, with better or no loss of correctness」，另外還有一節標題是 SWE-bench Verified。

這些數字全部來自專案自己的 benchmark，我沒有安裝、沒有重跑、也沒有驗證過它的測試方法。README 沒有在可見範圍內交代樣本數、repo 規模分布、任務類型，或 correctness 是怎麼判定的。在這種資訊密度下，那張表適合當成「這個方向可能有救」的訊號，不適合當成選型依據。

真正該注意的是它自己承認的失敗模式：標題寫的是「better or no loss of correctness」，等於保留了一種情況，也就是省了成本但正確率沒有提升。如果你的任務本來就偏難、agent 的失敗不是因為找不到檔案而是因為推理錯了，那麼把更多節點塞進 prompt 未必幫得上忙，反而可能佔掉本來就有限的上下文。

跟直接讓 agent 自己探索相比，差別在成本落在誰身上

最直觀的替代方案就是不裝任何東西，讓 Claude Code 用它原本的方式探索：grep、讀檔、追 import。這個做法的優點是零維護、零額外檔案、行為完全取決於 agent 當下的判斷，而且不會有圖譜過期的問題。

Graft 的差異在於它把探索成本從「每次任務重付」搬到「每次程式碼變動後重建」。這是一個前置投資模型：你先付一次建圖的成本，換取之後每個任務少付一點。所以它的經濟性取決於兩個比率，任務重複率有多高，以及程式碼變動有多頻繁。變動越頻繁，圖譜越容易落後於實際程式碼，而 README 說 init 之後每一輪都會在背景重建，這緩解了落後問題，但也意味著編輯期間有背景工作在跑。

另一個方向的替代方案是向量檢索式的程式碼索引，把程式碼切塊、算 embedding、用相似度找出相關片段。兩者的差別不是誰比較準，而是檢索的依據不同：向量檢索靠語意距離，Graft 靠明確的連結與 agent 自己沿著連結走。前者對「我記得有個東西在處理退款」這種模糊查詢友善，後者對「這個 API 被誰呼叫」這種結構性問題友善。Graft 選了後者，也因此不需要維護索引與 embedding 模型。

授權、維護與升級成本

授權是 MIT，這對內部工具與商業產品的整合都是相對寬鬆的選擇。我不是律師，以下是從工程角度看的幾點，不構成法律意見：MIT 允許修改與再散布，只要你保留著作權聲明與授權條款；它不提供專利授權的明示條款，如果你的組織對這點敏感，需要自己評估。另外 README 提到 telemetry 是 anonymous 且 opt-out，並連到一份 TELEMETRY.md；在受監管的環境裡，這份文件應該在安裝前先讀過，確認它送出什麼、以及關閉的方式。

維護成本方面，Graft 的設計讓日常負擔偏低：沒有常駐服務、圖譜不進版控、壞掉就重建。真正需要留意的是版本升級，因為它會寫入 .claude/ 底下的 hooks 與 statusline 設定。這些檔案是你 repo 的一部分，升級 CLI 之後如果 hook 的格式改變，行為可能跟預期不同。升級前先確認 .claude/ 底下的內容有沒有被改動，會比事後排查省事。專案在 2026 年 9 月仍有推送，但沒有檢索到任何 release，代表你可能是在追 main 分支而不是穩定的版本號，這對生產環境是一個要自己權衡的點。

編輯結論

Graft 適合已經在用 Claude Code、而且 repo 大到每次任務都要重新摸索的團隊；如果你的專案只有幾十個檔案，agent 自己 grep 兩次就找到了，多一層圖譜只是多一份要重建的快取。導入前先跑 graft init --dry-run 看清它會動哪些檔案，再確認 graft/ 有沒有被正確寫進 .gitignore，最後在一個真實任務上比對開啟前後的 tool call 次數。README 開頭那張表的數字來自官方自己的 benchmark，我沒有重跑過，導入決策不該只靠它。

官方來源

1. Issues
2. License: MIT
3. Project website
4. README
5. trailhq/Graft on GitHub