Hunch——你的AI助手遵循的Git原生決策圖

Hunch是一款面向開發者的工具，其核心理念是讓代碼庫記住“為什麼”。傳統AI助手每次會話都從零開始，重讀代碼、重新猜測意圖，甚至可能“修復”你上個月故意設計的內容，因為決策邏輯分散在PR、Slack和開發者的大腦中，而不是代碼倉庫裏。Hunch通過構建一個Git原生的決策圖，將每個提交和測試事件轉化為結構化的決策、Bug和約束，從而形成持久化的知識圖譜。

問題所在

每個AI會話都從零開始，模型重讀代碼、重新猜測意圖，然後愉快地“修復”你上個月故意做的事情——因為推理存在於PR、Slack和人們的頭腦中，而不是倉庫裏。典型助手記憶是當前代碼的臨時RAG，範圍僅限於當前會話，價值保持平坦。代碼庫只記錄最終狀態，從不記錄被拒絕的替代方案或必須遵守的不變量。沒有記憶，代理會重新發現你已經修復的Bug，並撤銷防止它的變通方案。

工作原理

Hunch的工作流程分為索引、學習和接地三個步驟。索引階段使用確定性方法映射代碼結構（函數、文件、組件之間的關係），無需LLM參與，快速且完全在本地運行。學習階段將每個提交轉化為決策，將失敗的測試標記為Bug並關聯可能原因，將重複或嚴重的Bug提升為約束——即AI必須遵守的規則。接地階段通過MCP服務器、自動維護的CLAUDE.md文件和鈎子命令，將帶有來源、置信度和證據的上下文反饋給AI助手。

推理圖

一個Bug衍生一個決策，一個決策衍生一個約束。這些鏈接讓AI代理能夠用證據回答“為什麼”以及“什麼不能打破”——每個節點都附加到其組件、符號和提交。例如，Bug 009：重置後可用的泄漏令牌（無狀態JWT無法在服務端吊銷，被auth.revocation.spec.ts捕獲），導致決策017：將會話存儲在Redis而非僅JWT（會話移至服務端，JWT僅攜帶不透明ID，替代方案被拒絕，後果被記錄，提交a1b2c3d作為證據），進而產生約束004：吊銷必須在服務端進行（絕不單獨依賴JWT過期來註銷，範圍限定在src/auth/**，在該範圍內的任何編輯前都進行檢查）。

內部功能

Hunch提供了四類能力：記憶、守護、檢索和團隊共享。

記憶——圖所持有的內容

• 來源追蹤：每條記錄都有來源、置信度和證據。自動捕獲的猜測保持建議性，只有你確認的才能用於阻斷。
• Git同步：圖作為純文件存在於代碼旁，通過推送/拉取同步，合併沒有衝突標記。
• 原子性與持久性：中斷寫入不會損壞圖，損壞狀態拒絕覆蓋好數據。
• 時間旅行：可以查詢任意提交時的圖，歷史永不被刪除。
• 私有記憶：開源代碼而不開源推理，敏感決策存在於你控制的私有倉庫中。
• 決策接地：文檔可能漂移，但圖不會，助手在編輯前被告知當前決策。
• 組件Wiki與規範台賬：從圖渲染Wiki，對每個文檔進行分級：接地、過時或未驗證。過時文檔會得到一份由Wiki管理的副本，更新到當前決策。

守護——阻止什麼

• 迴歸守護：阻止重新添加過去決策故意移除的代碼。
• 否決（決策）守護：阻止重新引入被拒絕的方法，即使該方法從未存在於代碼中。
• 冗餘守護：檢測已存在的重複代碼。
• CI約束守護：每個PR都會收到評論，指出其觸及的不變量和決策，並在確認的阻斷規則被破壞時失敗。
• 因果合併裁決：每個差異一個裁決（BLOCK/WARN/PASS），引用背後的決策和防止的Bug。
• 意圖一致性：檢查代碼是否仍然遵守記錄的設計（分層、必經路徑、依賴方向）。
• 永遠不犯第二次：糾正代理一次，它就成為所有未來會話中每個助手都必須遵守的規則。

檢索——如何獲取“為什麼”

• MCP原生雙向：助手詢問文件為何如此構建、更改會破壞什麼，以及Bug是否以前發生過，並記錄新決策。
• 免grep結構：一次調用返回倉庫映射、目錄內容、文件大綱或符號的定義位置及其調用者。
• 圖增強檢索：相比純搜索，召回率提升41.7%（@10），無需嵌入。
• 操作手冊記憶：證明的重複任務步驟，按需返回。
• 脆弱性報告：倉庫中最危險的代碼排名，附有真實Bug歷史。
• 深度綜合：多次獨立閲讀變更，調和成一條筆記，僅在一致處可信。

團隊——共享與評估

• 離線工作，零SaaS：沒有SaaS，沒有API密鑰，學習計入你已經支付的編碼訂閲。
• 共享團隊記憶：一個存儲跨分支、工作區、團隊成員和代理共享，新克隆自動連接。
• 多候選裁決：五個代理解決方案按架構適合度排序。

為何不同

典型代理內存是當前代碼的臨時RAG，時間範圍僅限當前會話，索引語法和文件嵌入，無寫入路徑，價值平坦。而Hunch的核心數據模型是決策、Bug和約束的精選圖，時間範圍是整個代碼庫的生命週期，索引的是意圖、因果和不變量，具有一流的寫入路徑（在提交和測試時學習），價值像飛輪一樣複合。它消除的不是“AI看不到足夠代碼”，而是“AI重複過去錯誤/破壞設計”。

開始使用

安裝非常簡單：Node 22.13+，運行npm install -g @davesheffer/hunch即可。然後在一個倉庫中運行hunch init，它會索引倉庫、安裝鈎子和合並驅動，併為Claude Code、Cursor、VS Code、Windsurf、Codex和Antigravity等編輯器配置MCP和規則。通過hunch backfill --since 90d可以回溯最近90天的歷史，快速填充決策圖。之後，在任何這些編輯器中，你可以直接問“為什麼這個會話模塊是這樣構建的？”——答案會從記憶中返回，並附上提交作為證據。

Hunch的價值隨時間累積：運行時間越長，決策圖越豐富，AI助手的表現越智能。它的設計理念是讓代碼庫記住“為什麼”，從而避免重複的錯誤。