智能體腳手架工程 (Agent Harness Engineering: The Ratchet Principle)

原始來源與檔名：20260512_2026-05-12T093101+0800-Agent Harness Engineering.md

來源：[[@addyosmani]] / X (Twitter) — 2026-05-10 原始檔名：2026-05-12T093101+0800-Agent Harness Engineering.md

NAPKIN | 餐巾紙

餐巾紙公式

Agent = Model + Harness (Scaffolding) Bad Model + Great Harness > Great Model + Bad Harness The Ratchet Principle = Every mistake becomes a permanent rule in the Harness.

如果你的 Agent 搞砸了任務，別怪大模型笨，也別等下一代模型發布。那不是「模型問題」，那是「配置問題」。Agent = 模型 + 腳手架 (Harness)。腳手架工程 (Harness Engineering) 是一門新學科，核心哲學是「棘輪效應」：Agent 每犯一個錯，你就在系統提示詞 (AGENTS.md) 裡加一條規則，或寫一個攔截 Hook。長此以往，一個二流模型在你的專屬腳手架裡，表現會遠勝過在通用框架裡的頂尖模型。

一句話

本文定義了 2026 年最熱門的工程學科：Harness Engineering (腳手架工程)。作者指出，Claude Code 或 Cursor 等工具本質上都是包裹在模型外層的 Harness。Harness 的核心工作包括狀態管理 (Filesystem/Git)、工具執行 (Bash)、記憶體壓實 (Compaction) 以及執行護欄 (Hooks)。最核心的方法論是「行為倒推」與「棘輪機制」，確保系統永遠不會在同一個地方跌倒兩次。

餐巾紙草圖

[The Anatomy of an Agent Harness]

[ Context / Memory Layer ] (AGENTS.md, Filesystem, Git)
           |
[ Hooks / Guardrails ] (Pre-commit checks, Destructive command blockers)
           |
[ ReAct Orchestration Loop ] (Planning -> Execution -> Verification)
           |
[ General Tools ] (Bash Sandbox, Headless Browser)

*The Ratchet:* Agent comments out a test -> Rule added: "Never comment out tests" + Hook added to block `.skip(`.

ROUND 1: SKELETON | 骨架掃描

“這篇文章在說什麼”

• 定義: Harness 包含系統提示詞、工具定義、基礎設施（沙箱）、調度邏輯、Hooks 與可觀察性工具。「如果你不是模型，你就是 Harness」。
• 觀念扭轉 (Skill Issue): Agent 犯錯不是模型笨，而是 Harness 漏接了。開發者的責任是透過架構（如分離計畫者與執行者）或 Hook（如型別檢查）來防堵錯誤。
• 棘輪機制 (The Ratchet): 把錯誤當作永久訊號。Agent 意外註解掉測試碼 -> 在 AGENTS.md 規定不准註解 -> 在 Pre-commit hook 阻擋 .skip(。系統提示詞裡的每一句話，都必須來自過去的一次真實血淚失敗。
• 核心元件:
  • 狀態: 檔案系統與 Git。
  • 工具: Bash 是最泛用且強大的工具。
  • 沙箱: 提供安全的執行與自我驗證環境。
  • 對抗上下文腐爛: 透過壓實 (Compaction)、工具輸出卸載 (Offloading) 與漸進式揭露 (Progressive disclosure) 節省 Context Window。
  • 長線執行: 透過強制 Loop、強制寫入計畫檔、分離產出與驗證 Agent 來避免提早退出。
  • 護欄 (Hooks): 成功時安靜，失敗時大聲報錯並注回 Agent 循環讓其自癒。
• 未來趨勢: Harness-as-a-Service (HaaS) 崛起，開發者將在 Harness 框架（如 Flue）上構建，而非直接對接 LLM API。

ROUND 2: DISSECTION | 血肉解剖

“憑什麼這麼說”

核心論證鏈

1. 能力的邊界由 Harness 決定，而非模型: 作者指出，相同的模型在不同的 Harness 中跑 Benchmark，分數會有巨大落差。這證明了「模型智商」已經不是瓶頸，「系統如何引導、限制並驗證模型」才是工程的核心。
2. “Success is silent, and failures are verbose.” (成功是安靜的，失敗是囉嗦的): 這句話道出了 Hook 設計的精髓。如果 Agent 寫對了代碼，Lint 靜默通過；如果錯了，Lint 必須噴出詳盡的錯誤堆疊 (Verbose) 並直接餵回給 Agent。這種「自動化背壓 (Back-pressure)」是 Agent 能自我糾錯的唯一物理基礎。
3. 動態演化的腳手架: 當模型能力提升（例如原生 Context Window 變大或指令跟隨變強），舊的 Harness（如複雜的記憶體壓實邏輯）反而會成為累贅。Harness 工程師必須像拆除建築腳手架一樣，隨著模型長大而動態移除冗餘架構。

關鍵證據

• 引用了 Claude Code 的架構設計，指出其絕大部分工程量都花在 Context Injection、Worktree Isolation 與 Multi-agent Firewall 上。這證明了頂尖的 AI 工具公司，其核心競爭力早已轉移到了 Harness 的設計上。

邊界條件

• 棘輪機制的副作用是「規則膨脹」。如果無限期地向 AGENTS.md 添加規則，最終會導致 Context 浪費與模型注意力分散（Lost in the middle）。因此作者強調，必須在「模型智力提升」時大膽刪除舊規則。

ROUND 3: SOUL | 靈魂提取

“還能怎么用”

• 知識連結: 完美總結了先前所有關於 Agent 架構的討論！Garry Tan 的 Skillify 就是棘輪機制的具體實現；而 CLAUDE.md 的 12 條規則，就是這篇文章所謂的「從血淚失敗中提煉出的檢查清單 (Pilot’s checklist)」。
• 深層洞見: “Every line in a good system prompt should trace back to a specific, historical failure.” (優秀系統提示詞裡的每一行字，都應該能追溯到一次具體的歷史失敗。) 這是對「Prompt 工程師」最嚴厲的鞭策。不要寫空泛的「請你是個好助手」，去寫「絕對不允許在未跑測試前執行 git commit」。
• 行動呼籲: 立刻檢視你的 Agent 系統（或你的 Claude Code 配置）。如果它今天犯了一個錯，不要只在對話框裡罵它。打開 AGENTS.md，寫下一條死規矩；或者寫一個 bash 腳本在它執行前攔截它。這才是建立複利系統的正確姿態。