# 策展 · X (Twitter) 🔥🔥🔥

> 作者：Addy Osmani (@addyosmani) · 平台：X (Twitter) · 日期：2026-05-10

> 原始來源：https://x.com/addyosmani/status/2053231239721885918

## 中文摘要

# Agent Harness Engineering

一個程式開發 Agent 是由模型加上圍繞著它所建構的一切組成。Harness engineering（harness 工程）將這些鷹架視為一個活生生的產物，每當 Agent 出錯時，就對其進行加固。

簡單來說：每當 Agent 失敗時，你都要設計一個永久性的解決方案，確保它永遠不會再犯同樣的錯誤。

過去兩年，業界一直在爭論模型：誰最聰明、誰寫的 React 最乾淨，或者誰產生的幻覺最少。雖然這些討論很重要，但卻忽略了系統的另一半。

模型僅僅是運行中 Agent 的一個輸入。其餘的部分就是 harness：圍繞在模型周圍的 Prompt、工具、context 策略、hook、Sandbox、子 Agent、回饋迴圈以及恢復路徑，這些東西讓模型能夠真正完成任務。

一個表現尚可的模型搭配一個優秀的 harness，其表現總是能勝過一個優秀的模型搭配一個糟糕的 harness。越來越明顯的是，最有趣的工程工作不在於選擇模型，而在於設計圍繞著它的鷹架。

這個領域現在有了名字。@Vtrivedy10 創造了「harness engineering」這個術語，並清晰地拆解了 harness 究竟是什麼，以及為什麼每個部分都存在。其他業界聲音，如 @dexhorthy 追蹤湧現的模式、HumanLayer 將 Agent 的失敗歸納為配置上的「技術問題」（skill issues）、Anthropic 的工程團隊發布關於長效應用程式設計的指南，以及 Birgitta Böckeler 探索使用者端的體驗——這些觀點正逐漸匯聚成同一個概念。

這篇文章將這些觀點串聯起來。

## 到底什麼是 Harness？

Trivedy 的核心定義已經完成了大部分的工作：

> Agent = 模型 + Harness。如果你不是模型，那你就是 harness。

Harness 包含了所有非模型本身的程式碼、配置和執行邏輯。原始模型並不是 Agent。只有當 harness 為它提供狀態、工具執行、回饋迴圈和可強制執行的約束時，它才會成為一個 Agent。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1778373936644-iaHH6JkuzaEAAYR1Tjpg.jpg)

具體來說，harness 包含：

- System prompt、CLAUDE.md、AGENTS.md、技能檔案和子 Agent 指令。

- 工具、技能、MCP 伺服器及其技術描述。

- 捆綁的基礎設施，例如檔案系統、Sandbox 和無頭瀏覽器（headless browsers）。

- 用於生成子 Agent、處理交接和路由模型的編排邏輯。

- 用於確定性執行的 hook 和中介軟體，例如 lint 檢查或 context 壓縮。

- 用於日誌、追蹤、成本和延遲計量的可觀測性工具。

核心上，Agent 是一個在迴圈中執行工具以達成目標的系統。真正的技術在於設計工具和那個迴圈。

雖然這代表了一個巨大的表面積，但這是你的表面積，而不是模型提供者的。Claude Code、Cursor、Codex、Aider 和 Cline 都是 harness。底層模型在不同平台間可能完全相同，但你所體驗到的行為主要由 harness 決定。

## 重新定義「技術問題」

當 Agent 做出荒謬的事情時，工程師通常會責怪模型，並將問題歸類為「等待下一個版本」來修復。

Harness engineering 的思維拒絕這種預設。失敗通常是有跡可循的。如果 Agent 忽略了某個慣例，就把它加到 AGENTS.md 中。如果它執行了破壞性的指令，就寫一個 hook 來封鎖它。如果它在 40 個步驟的任務中迷失了方向，就將架構拆分為規劃者（planner）和執行者（executor）。如果它總是產出有問題的程式碼，就在迴圈中加入型別檢查的反壓訊號（back-pressure signal）。

正如 HumanLayer 所言：「這不是模型的問題，這是配置的問題。」考慮效能基準測試：一個領先的模型在現成的框架中運行，其得分往往遠低於同一個模型在客製化、高度調優的 harness 中運行的表現。將模型移入一個擁有更好程式庫工具、更嚴謹 Prompt 和更敏銳反壓機制的環境中，可以釋放原始設定所無法發揮的能力。

現今模型在理論上能做到的事，與你實際看到它們做到的事之間，差距主要就在於 harness。

## 棘輪效應：每個錯誤都成為規則

Harness engineering 中最重要的習慣是將 Agent 的錯誤視為永久性的訊號，而不是可以重試並遺忘的偶然事件。

如果 Agent 發送了一個包含被註解掉的測試的 PR，且該 PR 被意外合併，這就是一個輸入。AGENTS.md 的下一個版本必須註明：「永遠不要註解掉測試；刪除或修復它們。」下一個 pre-commit hook 應該自動標記 diff 中的 `.skip(`。審查子 Agent 必須更新以封鎖被註解掉的測試。

只有當你觀察到真正的失敗時才應增加約束，且只有當更強大的模型使這些約束變得多餘時，才應將其移除。一個好的 system prompt 中的每一行都應該能追溯到一個具體的、歷史性的失敗。

因此，harness engineering 是一門學科，而不是一個一體適用的框架。針對特定程式庫的正確 harness，完全是由其獨特的失敗歷史所塑造的。

## 從行為反向推導

設計 harness 最有效的方法是從期望的行為開始，並建構提供該行為的組件：我們想要的行為 → 達成該行為的 harness 設計。

Harness 的每個部分都必須有明確的工作。如果你無法說出某個組件存在的具體行為是什麼，它就應該被移除。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1778373936666-iaHH6JvwebkAAT69Yjpg.jpg)

檔案系統與 Git - 持久狀態

檔案系統是基礎。模型只能在適合其 context window 的內容上運作。檔案系統提供了一個 workspace 來讀取資料、一個卸載中間工作的空間，以及一個讓多個 Agent 進行協調的介面。

加入 Git 提供了免費的版本控制，讓 Agent 可以追蹤進度、分支實驗並回滾錯誤。

Bash 與程式碼執行：通用工具

大多數 Agent 在 ReAct 迴圈上運作：推理、透過呼叫工具採取行動、觀察、重複。與其為每個可想像的動作預先建立工具，給予 Agent bash 存取權限讓它可以在運行時按需建立所需的工具。

Agent 通常擅長 shell 指令，這使得 bash 和程式碼執行成為自主解決問題的預設策略。

Sandbox 與預設工具

Bash 只有在安全運行時才有用。Sandbox 為 Agent 提供了一個隔離的環境來運行程式碼、檢查檔案並驗證工作，而不會危及主機。

一個好的 Sandbox 附帶強大的預設設定：預先安裝的語言執行環境、測試 CLI 和無頭瀏覽器，讓 Agent 可以觀察自己的工作並關閉自我驗證迴圈。

記憶與搜尋：持續學習

模型除了訓練權重和當前 context 外，沒有其他知識。Harness 使用記憶檔案（如 AGENTS.md）來彌補這一差距，將知識注入到每一次對話中。

對於即時資訊（如新的函式庫版本或即時資料），網頁搜尋和 MCP 工具會直接內建在 harness 中。

對抗 Context 腐敗（Context Rot）

當 context window 被填滿時，模型的推理能力會下降。Harness 使用三種主要技術來管理這種稀缺性：

- 壓縮：智慧地總結並卸載舊的 context，以防止 API 錯誤。

- 工具呼叫卸載：將大量的工具輸出（例如 2,000 行的日誌）儲存在檔案系統中，同時只在 context 中保留必要的頁首和頁尾。

- 漸進式揭露：僅在任務明確需要時才揭露指令和工具，而不是在啟動時載入所有內容。

長週期執行

自主的長週期工作容易受到提早停止和問題拆解不佳的影響。Harness 透過結構設計來對抗這些問題：

- 迴圈：攔截模型嘗試退出的行為，並強制它在新的 context window 中針對完成目標繼續執行。

- 規劃：強制模型將目標拆解為逐步的計畫檔案，並在每一步之後透過自我驗證 hook 檢查其工作。

- 分割：將生成和評估分離為不同的 Agent，防止模型在評分自己工作時固有的正面偏見。

Hook 是你的強制執行層

Hook 彌合了請求動作與強制執行之間的差距。它們在特定的生命週期中運行：在呼叫工具之前、檔案編輯之後或提交之前。Hook 可以封鎖破壞性指令、強制自動格式化以節省 token，並運行測試套件。

理想情況下，成功是安靜的，而失敗是詳細的。如果型別檢查通過，Agent 不會收到任何回饋；如果失敗，錯誤會直接注入回迴圈中進行自我修正。

這是規則手冊與工具選擇

儲存庫根目錄下的一個純文字 markdown 檔案仍然是槓桿率最高的配置點。然而，它必須被視為飛行員的檢查清單，而不是風格指南。保持簡短，並確保每一條規則都是透過過去的失敗所換來的。

同樣的原則也適用於工具。十個高度專注的工具永遠勝過五十個功能重疊的工具。

此外，由於工具描述會填入 prompt 中，惡意或草率的外部整合（如未經驗證的 MCP 伺服器）可能會在 Agent 開始工作之前就將糟糕的 prompt 注入其中。

這在生產環境中是什麼樣子

我看過最清晰的成熟 harness 公開圖示，是 Fareed Khan 對 Claude Code 架構的（估計）拆解。

![](https://pub-75d4fe1e4e80421b9ecb1245a7ae0d1a.r2.dev/curated/1778373936658-mediaHH6KJrbQAAQwjpg.jpg)

前一節中的幾乎每個概念都作為命名組件出現在這張圖表中。Context 注入是知識層。迴圈狀態存在於記憶體儲存和工作樹隔離器中。破壞性動作的 hook 位於權限閘道之後。子 Agent context 防火牆是整個多 Agent 層。工具調度註冊表是 MCP 伺服器和 bash 插入的地方。Claude Code 的發展軌跡與其底層模型一樣，都極度依賴 harness。

## Harness 不會縮小，它們會移動

隨著模型的改進，對 harness 的需求並不會消失，而是會發生轉移。

人們很容易假設更好的模型會讓鷹架變得過時。例如，最近的模型升級大幅減少了對「context 焦慮」緩解措施的需求。但隨著底線提高，上限也隨之提高。以前無法觸及的任務現在變得可行，帶來了全新的失敗模式。

Harness 中的每個組件都編碼了一個關於模型無法獨自完成什麼的假設。當模型改進時，過時的鷹架應該被移除，並且必須建立新的鷹架以達到下一個水平。

訓練迴圈呢？

Harness 設計與模型訓練之間存在一個活躍的回饋迴圈。

現今的模型通常會在迴圈中加入特定的 harness 進行後訓練（post-trained），從而產生一定程度的過擬合。模型在 harness 設計者優先考慮的特定動作（例如檔案系統操作、bash、子 Agent 調度）上變得異常出色。

這使得 harness 成為一個活生生的系統，而不是一個靜態的配置檔案，並證明了「最好」的 harness 是專門為你的獨特任務和工作流程所優化的那一個。

## Harness-as-a-Service (HaaS)

業界正在從基於 LLM API（提供補全）轉向基於 Harness API（提供執行環境）進行建構。SDK 現在開箱即用地提供了迴圈、工具、context 管理、hook 和 Sandbox。

與其從零開始建構編排，現代的預設做法是選擇一個 harness 框架，配置其核心支柱，並專注於領域特定的 prompt 和工具設計。

這就是為什麼故障排除可以擴展的原因：你是在調整一個結構良好的配置表面，而不是重新發明整個 Agent 架構。

## 未來走向

如果你看看今天頂尖的程式開發 Agent，它們看起來彼此之間比它們的底層模型更相似。模型各不相同，但 harness 模式正在趨同。業界正在迅速識別將生成式文字轉化為可交付軟體所需的承重鷹架。

最令人興奮的開放性問題正在超越單一 Agent：平行編排多個 Agent、使 Agent 能夠分析自己的追蹤紀錄以修復 harness 層級的失敗，以及建構能夠即時動態組裝工具的環境。

最終，這將是 harness 不再是靜態配置檔案，而開始更像編譯器運作的階段。

如果你正在尋找一個很棒的 Agent harness 框架，@FredKSchott 寫了 Flue。它非常穩健，顯然是受到這篇文章早期版本的啟發！

## 標籤

Agent, 自動化, 其他, Agent Engineering