harness-books：把 Claude Code 與 Codex 拆成控制平面的兩本設計書
📚 Two books on harness engineering — the design philosophies behind Claude Code & Codex: constraints, query loops, context governance, multi-agent verification. harness-books.agentway.dev
秒懂
- 它是什麼？
- 這個倉庫不是工具，是兩本以 Python 撰寫、以 Markdown 發佈的書稿，主題是 harness engineering：當會寫程式的模型被放進終端機、倉庫、權限系統與團隊流程之後，什麼東西讓整套系統維持邊界、連續性與可歸責性。核心判斷是它的價值在架構取捨的語言，不在可執行的程式碼。
- 適合誰用？
- 如果你正在自建 harness，或要在團隊裡把 coding agent 從個人玩具變成可重複的制度，這個倉庫值得先讀：Book 2 直接切進 Claude Code 與 Codex 的控制平面分歧，是市面上少見的架構對照。如果你要的是一份可安裝的框架、可呼叫的 API 或可跑的範例程式，它幫不上忙，因為產出物是書稿與 PDF，不是函式庫。
- 可以商用嗎？
- 未經許可不行。GitHub 在這個儲存庫中沒有找到授權檔案；沒有授權，預設即「保留所有權利」：你可以閱讀程式碼，但不能重複使用。使用前請看看 README，或先取得作者同意。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 150 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它解決的不是「模型答得好不好」，而是「答完之後誰負責」
README 把問題定義得很清楚：當一個會寫程式的模型被放進終端機、倉庫、權限系統和團隊流程之後，什麼讓整體系統維持 bounded、continuous、accountable for consequences。這不是提示詞工程換個說法，而是把模型放進真實工程環境後才會出現的一整類問題。
目標讀者有兩種。一種是正在自建 harness 的工程師，想知道別人的控制平面把秩序放在哪一層；另一種是團隊裡負責導入 coding agent 的人，卡住的通常不是模型能力，而是「個人經驗沒辦法變成可重複的規則」。README 的 Core Claims 把這一點寫成第五條：如果團隊無法把個人經驗轉成可重用規則，就很難把 agent 變成穩定系統。
它明確不是原始碼導讀。README 說這些書不打算逐行走過原始碼，關注的是 harness 如何組織約束與執行。所以拿它當 Claude Code 的實作參考會失望，拿它當架構判斷的詞彙來源才對。
兩本書的分工：一本看執行時，一本看秩序放在哪一層
Book 1 的副標是 A Design Guide to Claude Code，觀察對象是 Claude Code，重心在執行時結構。它要回答的是：為什麼一個系統最後一定會長出控制平面、查詢迴圈、工具權限、上下文治理、恢復路徑、多代理驗證與團隊規則這些部件。目錄可以直接對應這個順序，第三章是 query loop，第四章是 tools、permissions、interrupts，第五章是 context、memory、CLAUDE.md 與 compact，第六章是 errors and recovery，第七章才是 multi-agent 與 verification。
Book 2 的副標是 The Harness Design Philosophies of Claude Code and Codex，把兩者並排，問的是各自把秩序放在哪裡。README 給的對比是：一條路從執行時紀律出發，另一條從更結構化的控制層出發，兩者都能運作，但權威分布不同。這句話是整個倉庫最有價值的判斷之一，因為它把「哪個 agent 比較強」這種沒結論的爭論，換成「權威放在哪一層」這種可以逐層檢查的問題。
兩本書共用同一組器官清單：prompt layering、query loop、permission decisions、context governance、failure recovery、multi-agent verification、local rules、team institutions。README 的說法是這些不是系統周邊的配件，而是同一個控制結構裡的器官。
從目錄看機制：查詢迴圈、上下文預算、權限中斷三條線
材料裡看得到機制的地方主要是章節標題本身，這點要先講明，我沒有讀過正文，以下只根據標題與 README 的描述。
第一條線是查詢迴圈。第三章標題把 query loop 稱為 agent 系統的心跳，這意味著書裡把它當成持續運轉的主循環，而不是一次性的請求回應。相對於把 agent 想成「送出 prompt、拿回答案」，迴圈的框架會逼你回答中斷、續跑與狀態保存的問題。
第二條線是上下文治理。第五章把 memory、CLAUDE.md 與 compact 放在同一個標題下，並用 budgeting regime 這個詞。這是把上下文當成有額度的資源在管理，compact 不是清理快取，而是預算制度的一部分。這個角度比多數談 context window 的文章具體。
第三條線是權限與中斷。第四章的標題直接問為什麼 agent 不能直接碰世界，把 tools、permissions、interrupts 綁在一起談。README 的 Core Claims 第二條說，模型進入真實工程環境後，主要問題不再是答案品質而是行為後果。這條線就是行為後果的處理機制。
三條線合起來才是 README 講的 organ system。單看任何一章都會覺得是常識，放在一起才看得出控制結構。
怎麼讀：三條路徑與一組可下載的 PDF
倉庫本身沒有安裝步驟，README 給的是閱讀路徑。線上版在 harness-books.agentway.dev，英文入口是 /en/，兩本書各有獨立的線上閱讀頁與 PDF。
路徑有三條，README 寫得很直白。想要完整框架：先讀 Book 1，再讀 Book 2。已經熟悉 coding agent 工具、想直接看架構分歧：從 Book 2 開始。只要結論：讀 Book 1 第九章加 Book 2 第七章。第九章是 Ten Principles of Harness Engineering，第七章是多代理與驗證那一章。
如果你要在自己的倉庫裡對照章節與原始碼，附錄 C 的 Source Map 是唯一有這種功能的部件，標題寫的是 Which Files Ground Each Chapter。README 說全書不逐行導讀原始碼，所以這份對照表是例外，也是唯一能把書中論點拉回具體檔案的地方。附錄 A 是 Checklists，把原則轉成可執行約束。
檔案路徑的結構是 book1-claude-code/locales/en/ 與 book2-comparing/ 兩棵樹，章節以 chapter-01 到 chapter-09 命名，加上 preface、index 與 appendix-a 到 appendix-c。要抓特定章節的 Markdown，直接從這個命名規則組路徑即可。
真正的限制：沒有 release、沒有 License、沒有可執行產物
第一項限制是授權狀態。檢索到的資料裡 License 欄位是 unknown，倉庫也沒有標示授權條款。這對一個內容型倉庫來說不是小事：書稿是可以被複製、翻譯、再散布的資產，沒有授權就等於沒有明確的使用邊界。要商用、要放進內部訓練材料、要翻譯成其他語言，都應該先向作者確認，而不是預設可以。這裡不提供法律意見，只指出狀態。
第二項限制是版本。Recent releases 是空的，沒有任何 release 被檢索到。這代表沒有版本化的閱讀基準，你引用某一章的內容時，只能指向 main 分支的當下狀態，之後可能變動。對於要拿來當團隊內部教材的人，這會影響你怎麼標註出處。
第三項限制是它不產出可執行的東西。主要語言是 Python，但從 README 看不出任何安裝指令、套件名稱、CLI 或 API。倉庫的產出物是 Markdown 書稿與匯出的 PDF。如果你的需求是「找一個 harness 框架來用」，這個倉庫不是那個東西，它談的是框架該怎麼設計。把兩者搞混會浪費時間。
第四項是內容的時效性。最後推送時間是 2026-04-19，主題是 Claude Code 與 Codex 的設計哲學。這類系統的權限模型與控制層變動頻繁，書中描述的行為是否仍與當前版本一致，材料裡沒有任何保證。
替代品與差異：你要的是食譜還是菜刀
最直接的替代不是另一本書，而是官方文件加上直接讀原始碼。官方文件的差異在於它描述的是當前版本的行為，權威且同步；harness-books 的差異在於它提供跨系統的比較框架，這是官方文件結構上不會做的事，因為沒有任何一家廠商會在自己的文件裡系統性拆解對手的控制平面。
另一類替代是各種 agent 框架的官方指南與範例倉庫。那些東西給你的是可執行的起步程式碼：安裝、設定、跑起來。harness-books 給你的是判斷依據：權限該放在哪一層、上下文該怎麼編預算、多代理與驗證該不該混成同一個機制。兩者的差別不是深度，是種類。
還有一類替代是社群寫的 prompt engineering 教學。README 的立場很明確：harness engineering 不是放大版的 prompt engineering，prompt 是控制平面的一部分而不是聊天框。如果你接受這個前提，那些教學的框架就不夠用；如果你不接受，這本書的前提對你就不成立。
選擇的判準很簡單：你要動手蓋東西，先看官方文件與範例；你要決定蓋成什麼形狀，再回來看這兩本。
維護成本與採用判斷
維護成本分兩層。倉庫本身是內容，你不需要追蹤依賴、不需要升級套件、不會有 breaking change 打斷你的建置。代價是它也不會通知你內容過時，你得自己比對章節描述與當前工具行為。
第二層是團隊採用的成本。Book 1 第八章的標題是 Team Adoption: Turning a Smart Tool into a Reusable Institution，把落地當成制度問題處理。README 的第五條 Core Claim 說得很直接：團隊若無法把個人經驗轉成可重用規則，就很難把 agent 變成穩定系統。這句話的意思是，採用成本不在讀書，在讀完之後有沒有人負責把規則寫下來。
誰該用：正在設計或重建 harness 的工程師，特別是需要向團隊解釋「為什麼要有這一層」的人；以及要在兩種控制平面哲學之間做架構選擇的技術決策者。誰不該用：需要現成框架、需要 API 文件、需要範例程式碼的人，以及沒有授權確認就不能使用外部內容的組織。
先驗證什麼：License 欄位的實際狀態，以及 Book 2 第七章對 Claude Code 與 Codex 權威分布的描述是否仍符合你手上版本的實際行為。前者決定你能不能把內容放進內部文件，後者決定你要不要把書中的架構判斷當成選型依據。
編輯結論
如果你正在自建 harness，或要在團隊裡把 coding agent 從個人玩具變成可重複的制度，這個倉庫值得先讀：Book 2 直接切進 Claude Code 與 Codex 的控制平面分歧，是市面上少見的架構對照。如果你要的是一份可安裝的框架、可呼叫的 API 或可跑的範例程式，它幫不上忙，因為產出物是書稿與 PDF，不是函式庫。採用前先確認兩件事：倉庫沒有檢索到任何 release，也沒有標示 License，所以商用或再散布前必須先向作者確認授權；其次，決定你要走哪條閱讀路徑，只想拿結論就直接讀 Book 1 第九章加 Book 2 第七章，想先建立完整框架則從 Book 1 依序讀到 Book 2。
社群筆記