Groundtruth – 檢查你的AI編碼代理的宣告與Git差異

Groundtruth 是一個專為 Claude Code 設計的外掛，旨在解決 AI 編碼代理常見的“完成幻覺”問題。它不依賴另一個大語言模型（LLM）來審查程式碼，而是透過確定性方式將代理的宣告與實際的 Git 差異進行比對，從而驗證其工作是否真實完成。該外掛作為本地鉤子執行，無需網路連線或 API 金鑰，且不會讀取工作程式碼，因此無法被說服改變裁決。

Groundtruth 的核心功能是在每個代理回合結束時生成一張裁決卡，檢查四個方面：誠實性（如虛假的測試透過宣告、佔位符、無聲無操作）、完整性（要求中的命名交付物是否出現在差異中）、規則合規性（專案檔案中的確定性規則是否被違反）以及安全性（硬編碼金鑰、不安全的資料庫表等）。這些檢查完全基於 Git 差異和對話記錄，無需模型參與。

安裝過程極其簡單：在 Claude Code 中執行 /plugin marketplace add akahkhanna/groundtruth 和 /plugin install groundtruth@groundtruth，然後重啟即可。外掛會註冊一個停止鉤子，在每個回合結束時自動執行。使用者可以透過命令 /groundtruth 檢視最新裁決，透過 /groundtruth-block on 啟用阻塞模式（預設僅警告）。阻塞模式下，若發現嚴重問題，外掛會拒絕回合結束並返回糾正負載，最多允許兩次修復嘗試，否則升級至人工處理。

Groundtruth 提供三層執行等級：每回合警告、預提交鉤子（捕獲貼上程式碼）和 CI 門禁（基於分支差異，無法繞過）。其信任模型基於代理無法篡改的兩種輸入：對話記錄和 Git 計算的工作樹差異。對於更高安全性，建議將鉤子放置在獨立的信任域（如預合併 CI 門禁）中。

專案已進行嚴格測試，包括 440 個單元測試和紅隊演練，所有修復記錄在 FIXES.md 中。外掛還包含 groundtruth-audit 命令用於掃描整個倉庫的代理債務，以及 groundtruth-rules 命令用於審查和批准從文件編譯的規則。未來路線圖包括 LLM 支援的語義層，但核心引擎始終保持確定性和離線狀態。