Agent Harness Engineering
核心概念
1. Agent = Model + Harness
Viv Trivedy 的核心公式：
coding agent = AI model(s) + harnessHarness 是什麼：圍繞模型的所有程式碼、配置和執行邏輯——系統提示、工具、沙盒、orchestration 邏輯、hooks、observability。模型是輸入，harness 是讓模型能完成工作的全部機制。
為什麼重要：同一個 Claude Opus 4.6，在 Claude Code 內建 harness 和自訂 harness 下，Terminal Bench 2.0 分數差距極大。Viv 的團隊只改 harness，agent 從 Top 30 跳到 Top 5。模型的品質上限在 harness 設計，不在等下一個版本。
2. Skill Issue 重新框架
常見反應：agent 出錯 → 怪模型 → 等新版本。
Harness Engineering 的反應：agent 出錯是配置問題（skill issue），不是模型問題。
- agent 不知道某個慣例 → 加進 協作規則檔
- agent 跑了破壞性指令 → 加 hook 擋住
- agent 在 40 步任務中迷失 → 拆成 planner + executor
- agent 一直「完成」錯誤的代碼 → 把 typecheck 結果接回 loop
每個失敗都是可工程化的 signal，而不是「體質問題」。
3. Ratchet（棘輪）原則
操作方式：
- agent 犯錯 → 分析根因 → 加進 協作規則檔 / 規則檔 / hooks
- 規則只在有真實失敗時才加
- 模型進步讓規則過時了 → 才移除
協作規則檔 的兩個硬教訓：
- 保持在 60 行以內：規則少，每條才有分量；規則太多，每條都被稀釋
- 每條規則必須溯源到一個具體的過去失敗：不能靠腦補加規則
4. Harness 的六個層次
| 層次 | 內容 | 功能 |
|---|---|---|
| Filesystem + Git | 工作目錄、版本控制 | 狀態持久化、多 agent 協作基礎 |
| Bash + Code Execution | 通用工具執行 | 讓 agent 能自建所需工具 |
| Sandbox | 隔離執行環境 | 安全執行、允許清單管控、可平行擴展 |
| Memory + Search | 協作規則檔、web search | 跨 session 知識注入、補訓練截止後的資訊 |
| Context 管理 | Compaction、offloading、skills | 對抗 context rot，讓 agent 保持清醒 |
| Long-horizon Execution | Ralph Loop、planning、evaluator | 多步驟任務不失控、planner/generator/evaluator 分離 |
5. 從期望行為反推 Harness 設計
Viv 的設計框架：先定義想要的行為，再推導哪個 harness 元件能交付它。
想要的行為 → 對應的 harness 元件
─────────────────────────────────────
agent 不亂改慣例 → 協作規則檔 的規則
agent 不跑破壞性指令 → pre-tool hook
agent 測試通過才結束 → typecheck 回壓信號
agent 不在 40 步後迷失 → planner + checkpoint
agent 多 session 不失憶 → 協作規則檔 自動注入每個 harness 元件都應該有一個明確的「它存在是為了防止 X 行為」的答案。
6. Harness-as-a-Service（HaaS）趨勢
Claude Agent SDK、Codex SDK、OpenAI Agents SDK 都在往「給你 runtime，你來調整配置」方向走。
開發者的工作從「自建 loop + 自己管 conversation state」，變成「在四個維度上配置：system prompt、tools、context、subagents」。
意義：harness 不再是從零打造，而是在有良好抽象的框架上，針對你的任務做領域特定的調整。
7. Claude Code 的五層 Harness 結構
warmwater.dev 的 Harness Engineering 系列提出了一個針對 Claude Code 工具鏈的五層操作結構，和 Viv Trivedy 的六層互補（前者更抽象，後者針對 Claude Code 特定配置）：
| 層次 | 元件 | 角色 |
|---|---|---|
| 1 | 規則檔 | 系統提示層——行為規則、邊界、工作哲學；保持 60 行以內，規則過多每條都被稀釋 |
| 2 | Hooks | 自動化信號層——工具執行前後插入邏輯；透過 stderr 發送信號，LLM 決定是否採取行動 |
| 3 | Skills | 可載入能力層——三層 Progressive Disclosure：metadata 常駐（~35 tokens）→ 觸發後載入 body → 執行時讀取 resources |
| 4 | Plugins | 功能打包層——把相關 Skills + MCP + Hooks 打包成可共享、可移植的單元 |
| 5 | MCP Servers | 外部整合層——連接外部 API 與資料源；credential 邊界在 server 端管控，不進 prompt |
維護節奏：每 3–6 個月審視一次。判斷標準是 benchmark gap：移除某條規則後行為沒有下降，這條規則就應該刪掉。靠感覺維護 harness 是盲目工程化；老規則可能在不知不覺中阻礙新模型能力。
（來源：warmwater.dev / 溫煜鈞；https://warmwater.dev/blog/claude-code-harness-over-model）
8. 四個可預測的 AI 編碼失敗模式
warmwater.dev「計畫模式」文章整理出四個在 agent 執行中反覆出現的失敗模式，以及對應的 harness 設計解法：
| 失敗模式 | 描述 | Harness 設計解法 |
|---|---|---|
| 直接開始編碼 | 沒有規劃就動手，改了多個檔案才發現方向錯誤 | Plan Mode：書面計劃批准後才動 code |
| 猜 bug | 不讀完整錯誤信息，靠猜修 bug，繞了大圈 | Iron Law：強制讀完整錯誤信息再診斷 |
| 宣稱完成但沒驗證 | 任務做完，沒跑測試或驗收，問題留到後面才爆 | Gate Function：宣告完成前必須通過門檻檢查 |
| 長 session context 污染 | session 過長，AI 受早期上下文干擾，產出不一致 | Controller-Worker 架構：每個子任務由獨立 subagent 從零 context 開始 |
Iron Law + 反合理化表：在 harness 中植入「鐵律」本身不夠——模型會自我合理化繞過它（「這次情況特殊⋯⋯」）。有效的強制執行需要同時加入「反合理化表」：預先列出 AI 可能用來繞過此規則的理由並逐一反駁，讓模型在執行前就看到自己的合理化路徑。
Gate Function 語法：
BEFORE [宣告任何任務完成]
→ 必須執行：[測試清單 / 驗收標準]
→ 確認通過後
ONLY THEN [繼續下一步 / 回報完成]Controller-Worker 架構：Controller 的責任是準備完整、自包含的提示詞（含背景、邊界、預期輸出），確保每個 Worker subagent 啟動時 zero session history——不靠 context 繼承，只靠 Controller 注入的信息包。這是「防污染」的工程化實作，也是為什麼 Controller 要花時間準備提示詞而不直接轉發指令。
（來源：warmwater.dev / 溫煜鈞；https://warmwater.dev/blog/superpowers-plan-mode-ai-agent）
核心框架
Harness 設計的四個配置維度
System Prompt（行為邊界）
↓ 例：協作規則檔、規則檔
→ 告訴 agent 不能做什麼、怎麼做、慣例是什麼
Tools（能力範圍）
↓ 例：bash、Playwright、Context7、Sequential Thinking
→ 10 個精準工具 > 50 個重疊工具；每個工具的 description 是 prompt
Context（資訊密度）
↓ 例：compaction、progressive disclosure、tool offloading
→ 讓 context window 裡的每個 token 都有意義
Subagents（協作結構）
↓ 例：planner/generator/evaluator 分離
→ agent 自評自己的工作會偏正向；分離 evaluator 才能客觀驗收Harness 不縮小，只是移動
隨著模型進步，舊的 harness 問題消失，但新的任務空間打開，帶來新的 harness 問題：
- Opus 4.6 解決了 context anxiety（不再因接近 context limit 而提早收工）
- → 之前的「緊張感緩解 scaffolding」可以移除
- → 但現在可以做更複雜的多日任務，需要「multi-day memory policy」和「cross-agent 協作設計」
Claude Code 不能只待在角落
矽谷叔叔的 Claude Code 工作流文章提供了另一個很實務的 harness 角度：很多人覺得 Claude Code 只能做小事，原因不是模型差，而是沒有把它接進真實工作流。
三個可轉成 harness 設計的做法：
| 做法 | Harness 對應 | 安全邊界 |
|---|---|---|
| 讓 Claude Code 接觸 Browser | Tools / workflow surface | cookie 與登入狀態要限制任務範圍 |
| 把重複流程 script 化 | Deterministic tool offloading | script 要可審、可重跑、可回滾 |
| 用 MCP Server 延伸 API / 工具 | Tools + credential boundary | API key 不進 prompt，server 端要管 secret / auth / logs |
這補強了本篇的核心：agent 的能力上限不只是模型，而是它被允許接觸什麼、反覆流程是否工程化、敏感能力是否被隔離。
對 FLUX Vault 的應用
規則檔 就是 Vault 的 harness，這個重新框架讓現有設計的用意更清晰：
| FLUX Vault 元素 | Harness 對應 |
|---|---|
規則檔 | System Prompt（行為邊界） |
延伸方向.md | Memory（有效模式 + 踩坑 → 下次行為調整） |
| 快速指令觸發表 | Skills with progressive disclosure |
| 禁止事項 Section 05 | Pre-tool hooks（禁止破壞性操作） |
| Session 結束行為校準 | Ratchet 棘輪機制 |
延伸方向.md | Planner（任務前先定 spec，再執行） |
行動 App 開發起步建議： 開始讓 AI 寫 App 之前，先設計 harness：
- 建立
行動 App/規則檔（system prompt 層） - 定義工具允許清單（tools 層）
- 設計 spec 模板（context 層）
- 等需要多個 subagent 協作時，加入 planner/evaluator 分離（subagents 層）
我的觀點
確認：2026-05-24
規則檔 就是 Harness 這個重新框架，讓我意識到自己在做什麼
我一直在建 harness，只是之前沒有這個詞。Section 07 的「每次 AI 犯錯就加一條規則或踩坑紀錄」就是 Ratchet 原則。延伸方向.md 的有效模式和踩坑紀錄就是 memory 層。快速指令觸發表就是 progressive disclosure。現在有了這套語彙，可以更有意識地設計而不是靠直覺累積。
Ratchet 原則是 規則檔 Section 07 的理論基礎
以前寫「重複犯同一類錯誤就加進禁止事項」是實用主義，現在知道這叫 Ratchet——每個失敗都是永久 signal，累積成更好的 harness。這個框架也讓我更清楚 什麼時候不應該加規則：沒有真實失敗就不加，不然規則會膨脹失焦。
Leeway：YAML 決策樹作為 Ratchet 的結構化延伸（2026-05-27 補充）
Claude Taiwan 社群（Marcus Chang，2026 年）分享的 Leeway 概念——用 YAML 決策樹約束 Agent 執行順序——可以理解為 Ratchet 原則的一個進化形式：不只是文字規則，而是把「執行順序」本身結構化，讓 Agent 每次做同類任務時都走相同路徑，確保可重現、可稽核。
Leeway repo README 查核補充（2026-05-28）
實際讀取 README 後，Leeway 的定位比最初的「YAML 決策樹概念」更為完整。它明確把自己定位在兩個極端之間：OpenClaw（Agent 完全自主決定路徑，彈性但不可預測）和 n8n（人工設計剛性腳本，可預測但無 AI 靈活性）——Leeway 的設計是「人定決策圖，AI 在每個節點執行」。這個定位和本篇 Harness 設計的核心一致：由 harness 定義邊界，由 AI 在邊界內發揮。
技術層面，Leeway 是一個完整的 Python harness 框架（MIT，190 項測試全通過），包含：21 個內建工具（File I/O / Web / Bash / Tasks / Cron / Memory / MCP）、hooks 生命週期（before/after tool execution）、MCP 支援、cron 排程、skills 模組化、plugins 打包、remote triggers、以及多層權限管控（Plan mode / Full auto / Default）。這讓 Leeway 成為「harness-as-a-service 的本土具體實作」——而不只是一個 YAML 規則概念，是值得深入追蹤的演進軌跡。
warmwater.dev 補充視角：三層模型、越做越薄、規劃是新的編碼（2026-05-28 補充）
溫煜鈞（warmwater.dev / Backend Engineer @ Trend Micro）的 Harness Engineering 系列文章提供了幾個補充本篇的重要視角：
三層工程模型：Prompt Engineering（單次訊息品質）→ Context Engineering（信息供給策略）→ Harness Engineering（執行基礎設施）。三者不是遞進關係，而是不同抽象層次——當你決定要建「執行代理」而非「問答系統」的那刻，harness 就應該和 prompt 一起進入考量。Harness 解決的是「模型從文字工具轉為執行代理後」才出現的四類問題：操作副作用不可逆、任務狀態需跨 session、資源成本需管控、多 agent 協作需協調。
越做越薄，不是越做越複雜：Manus 團隊在半年內重寫 Harness 五次，每次方向都是簡化——用通用 shell 替代複雜工具定義，用結構化交接替代管理 agent。這是反直覺的洞察：如果你的 harness 越做越複雜，大概率是在用基礎設施補償本來可以直接信任模型的地方。這和 Ratchet 原則方向一致：只有真實失敗才加規則，模型進步讓規則過時就移除。
規劃是新的編碼（Boris Tane / Cloudflare）：永遠不要讓 Agent 在審查和批准書面計劃前寫代碼。Agent 一旦開始執行，中途糾偏成本比人類寫 code 時更高——它可能已修改多個文件、建立多個前提假設。這和 FLUX Vault 的 延伸方向 完全對應：先定 spec、再執行。
有人值守 vs 無人值守並行：位置取決於 harness 成熟度，不是模型能力。Stripe 能無人值守，是因為有完整預暖開發環境和 CI 整合。FLUX Vault 目前是有人值守——這是 harness 仍在建立的正常狀態，不是限制。
（來源：warmwater.dev / 溫煜鈞；https://warmwater.dev/blog/harness-engineering-ai）
Plugin 層的具體化（2026-05-31 補充）
本篇的第 4 層「Plugin = 功能打包層」已有專篇展開：延伸方向。補充視角：
- Plugin 不只是把 Skills 打包，而是把整個 harness 配置（Skills + Commands + MCP + Hooks + manifest）打包成可安裝單元
anthropics/knowledge-work-plugins展示了 Plugin 升級為「職能工作包」的可能性——按工作角色而非工具清單組織能力（詳見 延伸方向）- Codex App 的 plugins（Browser、GitHub、Documents 等）是同一邏輯的不同實作：capability bundle 作為 harness 競爭的核心戰場
胡嘉璽報告的四個補充視角（2026-06-03）
Context Rot 與 FLUX Vault session 設計的呼應 報告提出 Context window 甜蜜區 40–60%、有效上限約 17 萬 tokens——這解釋了 FLUX Vault「短 session + handoff」設計的底層邏輯：每次 session 結束前主動輸出交接文件，本質上是在 context rot 發生前強制清場。規則檔 的「session 結束行為校準」機制，就是把 context management 制度化為流程。handoff 不只是方便性設計，而是對抗 context rot 的主動 harness 機制。
Codex 任務邊界 = Sub-Agent 脈絡防火牆的工程化 「Sub-Agent 是脈絡防火牆」讓 cowork-to-codex 任務文件的邊界說明有了理論根據：「必讀文件清單」是 Controller 注入的信息包，「不需要讀」的邊界說明是防火牆定義。每一條邊界限制都是在防止雜訊污染 Codex 的 context。以前靠直覺寫邊界，現在知道這是 harness 設計裡防火牆機制的具體實作。
Section 09 退場機制是 Level 3 清潔代理的人工版 報告「Level 3：清潔代理定期回收技術債」在 FLUX Vault 的對應是 Section 09 的操作型文件退場機制——定期清理 操作紀錄/、刪除已吸收的 結果紀錄、維護 Raw 佇列。目前是人工觸發 + AI 輔助執行，而非全自動清潔代理。若清理頻率夠高，可評估透過 Cowork scheduled task 自動化（對應學習與優化待辦的「Vault 自動化」條目）。
Runtime 層是真正的護城河 模型層商品化 + 協議層開放（MCP 等事實標準）= 護城河在 Runtime 層（Claude Code / Cowork）和 Control Plane 層。FLUX Vault 工具鏈（規則檔 + 延伸方向.md + task-spec-SOP）是在 Runtime 層累積個人護城河——讓 AI 工具在「我的 harness 上」比別人的預設配置跑得更好。這解釋了持續維護 規則檔 Ratchet 機制的長期複利效應：護城河不是別人拿不走的模型，而是拿不走的 harness 設計。
eval 層是我 harness 的結構性缺口（2026-06-06 自我體檢）
拿 agents-best-practices（延伸方向）的 audit checklist 對 FLUX Vault 跑了 5 面鏡子體檢（Legibility / Permission / Context / Skills / Mechanical invariant，完整結果見 延伸方向），得到一個我自己沒意識到的結論：我的 harness 強在「規則層」和「可讀層」，但弱在「機械驗證層」。
我一直把 Ratchet 原則做得很勤——每次失敗就加一條規則或踩坑紀錄。但 checklist 點出我漏掉的下一步：成熟的 harness 不只「記住」失敗，而是把失敗機械攔截。我已經在 wiki 寫入層做了兩支 hook（protect_evergreen 擋寫 evergreen、validate_wiki_frontmatter 驗 frontmatter）——所以機械層不是全空，方向也對。但這兩支只覆蓋「寫進 wiki 時的完整性」，我其餘的規則仍多是寫給 AI 讀的 prompt-level 指示，靠 AI 自律 + 每個 session 的人工覆核執行。三個還沒被機械攔截的缺口：
- Skill eval 真空：vault-prescreen 等 skill 沒有 activation / output eval。本次 Threads 佇列清空時，#3 Trellis 被誤判為新增量（它其實早已入 AI工具 - Agent Session Handoff Governance），就是 output 沒被 eval 攔下、靠 Cowork 人工覆核才抓到的活例。
- 驗證靠記憶：入庫 SOP 的
rg/parser 驗收是「請 AI 記得跑」的 prompt 指示，不是會自動執行的 validator——AI 可能略過而無人察覺。 - 無 regression：踩坑寫進 延伸方向 只是文字規則，下次同類錯誤沒有自動測試攔截。
這把 Ratchet 原則往前推了一格：Ratchet 的終點不是「規則清單」，而是「validator / eval 清單」——文字規則是 Ratchet 的初級形態，把反覆失敗固化成機械檢查才是成熟形態。這也解釋了為什麼我目前的品質完全依賴人工覆核：因為驗證層還沒從 prompt 下沉到機制。可遷移性：這個缺口將來 行動 App / 教學管理系統 agent 一定會撞到，屆時可直接用 agents-best-practices 的 mvp-agent-blueprint 起手，把 eval / launch gate 從第一天建進去。
外部同構驗證＋兩個缺口機制（2026-07-10，科技翰林院 Fable 5 雙文）
林思翰（科技翰林院，競品 v3 §五 🟡C 追蹤對象）7/4〈Fable 5 駕馭工程 Harness Engineering 實戰提示詞〉＋7/7〈四天用掉 6 億 tokens〉——與我 07-03 用 Fable 5 重寫 規則檔 v3.0 同一週、互相獨立地做了同一件事（用最強模型立制度而非寫 code），是本頁框架至今最完整的外部同構驗證：一份正本＋薄索引（≤150 行只路由）＝規則檔 S03 觸發式路由；「貴模型解 1 題、便宜模型抄 49 題」＋升降級路徑＝延伸方向.md；「驗證不自驗」派 fresh-context 對抗審查＝中風險 read-back；「判斷力外化成 rubric、每條附正反例」＝延伸方向.md。同構部分不重複入庫，真正的增量是他有、我沒有的兩個機制：
- 環境查證（設定 vs 實際執行）：他實查 95 筆執行紀錄，發現設定檔寫 xhigh、83 筆實跑 medium；自動記憶管線資料表 0 筆＝每個 session 都在失憶。我的制度隱含假設「規則寫了＝生效」——排程是否照 prompt 跑、skill 是否真被載入、hook 是否真攔截，沒有任何儀式驗證。這是 2026-06-06 體檢「機械驗證層弱」的新子項：eval 的對象不只是產出，還有 harness 自身的 runtime 狀態。可落地形態＝季度審查加「制度運行對帳」一項（排程 prompt 備份 vs 實際 result 抽對、hook 攔截紀錄抽測）。
- 存量制度減法稽核：立制度後第三天讓 Fable 5 回頭「只挑錯、不修改」稽核制度本身（含它自己寫的部分），抓出 15 條——5 條規則互相矛盾、4 條過時護欄、5 條制度自我違反、1 條與現實脫節。我有 Codex 異源評審，但它審的是變更增量（審查包）；沒有「定期審存量」的儀式——而 規則檔 v3.0 同樣出自 Fable 5，「由模型 N 維護的系統，會保留模型 N 看不見的錯誤」對本庫同樣成立。可落地形態＝半年一次減法稽核（fresh-context 或異源模型對全套規則檔只列問題清單、不修改，白澤裁決），與 延伸方向 既有機制銜接。
趨勢面：OpenAI 已於 2026-02-11 官方使用 Harness Engineering 一詞（https://openai.com/index/harness-engineering/ ）；2026 年 7 月中文內容圈再出現制度化實作擴散訊號（科技翰林院雙文＋曾思遠演講口徑「Prompt+Context+Harness+Loop」）——概念主流化已有數月，本庫 協作制度 制度獨立於中文圈這波擴散之前成形，差異化窗口在「個人知識工作者的制度化實作」而非「首創用詞」。（來源：openai.com/index/harness-engineering ＋ techhanlin.tw/fable-5-harness-engineering ＋ techhanlin.tw/claude-fable-5-max-real-world；延伸方向；2026-07-10 Codex 複審修正原「同週 OpenAI 開始使用」時間錯誤）
待深化的問題：
- [x] Ratchet → validator 升級試點（2026-06-06 開）→ ✅ 結案（2026-06-10）：試點在生產中驗證成功。vault-prescreen 延伸方向.md Step 5「Verdict 自檢」（06-06 加入）於 2026-06-10 的 7 題查證批次真實攔截一次誤判——Agent Handoff Kit 初判「增量」，自檢規則（查目標頁既有涵蓋）發現頁內 06-04 npm 驗證節已答原問題，輸出前改判「已整合＋輕增量」，正是 06-06 #3 Trellis 誤判的同型錯誤。結論：①可行性✅——文字規則寫進 skill 自檢步驟即可機械執行，不需 hook／code；②維護成本≈零（一段 延伸方向.md 文字）；③推廣判準＝「可機械驗證的前置檢查」優先做成 skill 內自檢清單，hook 留給跨 skill 的硬邊界（如 code_readonly_gate）。原「規則檔 vs Hooks 臨界點」問題由此收斂：臨界點不在規模，在「違規後果是否不可逆」——可逆的用 skill 自檢，不可逆的才上 hook。
- 協作規則檔 60 行上限：✅ 已確認（2026-05-31）。規則檔 目前 300 行，不會接近 60 行。分析：核心規則段落（Section 00–05, 07–08）約 103 行，Section 06（AI 工具行為紀錄）106 行，Section 09（退場機制）58 行。60 行上限是針對軟體開發專案的 協作規則檔；FLUX Vault 的 規則檔 承擔更廣泛的功能（session governance、Codex 交接觸發、行為校準規則），不宜類比。實際應用原則：關注單條規則的清晰度和可追溯性（每條規則要能溯源到真實失敗），而非總行數。
- 行動 App harness 設計：等開發啟動時，用這篇作為 harness 設計的起跳框架
- 先寫憲法再建系統（來自 ryanx0621/Atlas-World，2026-06-03）：在 agent 行為出現之前先定義約束層，是 規則檔 設計的同一原則。Atlas-World 的身份連續性函數 C(S₀, S*) 也值得參考：用四維度（記憶/價值觀/性格/時間）量化「合併前後還是不是同一個 agent」——可套用在 session handoff 的品質評估，思考「下一個 session 的 AI 接回多少這次的脈絡？」
- ~~warmwater.dev 的 Claude Code Harness Engineering 系列（8 篇）值得系統性讀完，特別是「Task Continuity：Claude Code 的 Session 設計」與「Hooks 完整指南」——待條件成熟時深化~~ ✅ 已系統讀完（2026-05-28）：五層 Harness 結構、四個失敗模式與設計模式已補入小節 7–8；Task Continuity 三層框架補入 AI工具 - Agent Session Handoff Governance；三層載入機制與 Description=搜尋索引原則補入 AI工具 - Claude Skills 設計原則與工作流對應
可連結的主題
- 延伸方向 — 規則檔 / hooks / skills 的實際結構設計
- AI工具 - Claude Code 多代理工程團隊方法論 — subagents 上下文隔離、planner/evaluator 分離的工程實踐
- 延伸方向 — Spec 作為 harness 的 context 層
- 延伸方向 — Tools 層的設計原則
- 延伸方向 — Long-horizon execution 的具體實踐