Ancienttwo/repo-harness

解決的問題

repo-harness 解決了 AI 編碼會話依賴於易失性聊天記憶的問題。當開發人員在不同的 AI 代理（如 Claude 和 Codex）之間切換或開始新會話時，之前的計劃、進度與決策的上下文往往會遺失，迫使代理花費 Token 與時間重新發現儲存庫結構與當前狀態。

工作原理

本專案實現了一種以檔案為基礎的流程，其中專案狀態的「真相」存在於儲存庫本身，而非聊天歷史中。它使用 CLI 與一套與主機適配器（例如 ~/.claude/settings.json 與 ~/.codex/hooks.json）集成的 Hook 系統。

核心機制包括：

• 會話移交 (Session Handoffs)：Hook 將上下文、計劃與移交內容寫回專案檔案（例如 .ai/harness/handoff/resume.md），允許新會話從上次中斷的地方準確恢復。
• Token 效率：利用預建的 CodeGraph 索引進行結構化查詢，並透過 context-map.json 進行漸進式上下文載入，減少了昂貴的 grep-and-read 循環需求。
• 護欄 (Guardrails)：程序內變更保護可以在活動計劃未標記為「已批准 (Approved)」或「執行中 (Executing)」時阻止實作編輯。
• 結構化產物：將儲存庫組織成特定的介面，用於規範 (docs/spec.md)、計劃 (plans/) 與任務契約 (tasks/contracts/)。

適用對象

專為使用 AI 代理（特別是 Claude 與 Codex）處理複雜、長期編碼任務，並希望擁有可重複、可驗證且具備 Token 效率之流程的 AI 工具所有者與開發人員設計。

亮點

• 以檔案為基礎的狀態：將代理協作從聊天執行緒轉移到儲存庫本地檔案。
• 漸進式上下文載入：使用小型根上下文與能力區塊來節省 Token。
• 自動化移交：捕獲會話狀態與 dirty-bit 事件，以促進無縫會話恢復。
• 硬性強制關卡：能夠根據活動計劃的狀態阻止程式碼編輯。
• MCP 連接器：可選的邊車 (sidecar)，用於向 MCP 用戶端公開流程產物。