Agent Harness Engineering：代理人工程架構
互動投影片：ai-agents/agent-harness-engineering
鍵盤←/→翻頁，Space自動播放或暫停。
本文歸檔自「Agent Harness Engineering」投影片，整理 Addy Osmani 於 2026 年對 coding agent 架構的觀察：真正決定 agent 表現的，通常不是模型本身，而是模型外層的 harness。
核心命題
coding agent = model(s) + harness
模型負責推理與生成，但 coding agent 的實際能力，來自整個外層執行系統：
- prompts
- tools
- context
- hooks
- sandbox
- subagents
- logs
- traces
- feedback loop
Claude Code、Cursor、Codex 之間的差異，不只來自底層模型，也來自它們如何包裝、限制、引導與觀測模型。
什麼是 Harness？
如果你不是在訓練模型，你大多數時候其實都在做 harness engineering。
Harness 包含：
| 層次 | 內容 |
|---|---|
| 文件與規則 | System prompt、CLAUDE.md、AGENTS.md、skill files |
| 工具與技能 | Tools、MCP servers、瀏覽器、搜尋、API |
| 執行環境 | Filesystem、Git、Bash、Sandbox |
| Context 管理 | Compaction、tool-call offloading、progressive disclosure |
| 任務編排 | Planner、executor、evaluator、subagent dispatch |
| 強制機制與觀測 | Hooks、permission gate、lint、test、logs、traces |
Harness 的任務不是讓模型「更聰明」，而是讓模型在正確的資訊、工具、限制與回饋中工作。
不是 Model Problem，而是 Config Problem
很多 coding agent 的失敗，看起來像模型能力不足，但實際上是 harness 配置不足。
| 症狀 | Harness 修正 |
|---|---|
| 不知道 coding convention | 寫進 AGENTS.md |
| 執行破壞性指令 | 用 hook 攔截 rm -rf、DROP TABLE 等危險操作 |
| 40 步任務中途迷失 | 拆成 planner + executor |
| 產出壞 code 卻以為完成 | 把 typecheck、lint、test 結果接回 loop |
同一個模型，在不同 harness 下可能有巨大表現差距。Terminal Bench 2.0 的例子指出，同樣模型只改 harness，排名可以大幅提升。
每個錯誤都應該變成規則
Agent 錯誤不是一次性故事，而是永久信號。
好的 AGENTS.md 不應該是腦暴式規範，而應該是從真實失敗逐步 ratchet 上去的 checklist。
範例：Agent 送出含 commented-out test 的 PR。
- 在
AGENTS.md寫明：刪除 test，不要 comment out。 - 加 pre-commit hook 檢查
.skip(/xit(。 - 讓 reviewer subagent 把此類 PR 標為 blocker。
原則：
- 保持 60 行以內。
- 每條規則要能追溯到一個真實失敗或硬性外部約束。
- 越多規則，每條規則的注意力權重越低。
從 Behaviour 出發，不是從 Feature 出發
不要先問「agent 需要哪些功能」，要先問「我希望 agent 表現出什麼行為」。
常見 harness 能力映射：
| 期望行為 | 需要的 harness 能力 |
|---|---|
| 能安全修改專案 | Filesystem + Git |
| 能自動驗證 | Bash + code execution |
| 能隔離風險 | Sandbox |
| 能補齊專案知識 | Memory + search |
| 能處理長任務 | Context 管理 |
| 能強制遵守規則 | Hooks |
Feature 是表面，behaviour 才是設計目標。
Context Rot：Context 填滿，模型退化
模型的推理能力會隨 context 填滿而下降。長任務需要把 context 當成有限資源管理。
三種常見技術：
| 技術 | 用法 |
|---|---|
| Compaction | 把歷史對話壓縮成必要摘要 |
| Filtering | 只載入與當前任務相關的工具、文件、trace |
| Offloading | 把大型資料放到檔案、資料庫、外部資源，只把索引放進 context |
長任務可用 context reset：產生精簡交接檔，重啟乾淨對話，再從必要狀態繼續。
Planning、Evaluators 與 Ralph Loops
複雜任務不應只靠單一 agent 一口氣做完。
可用模式：
- Planning：把目標拆成步驟寫入 plan file。
- Evaluators：分離生成與評估，避免 agent 替自己打高分。
- Definition of Done：generator 與 evaluator 先協商完成標準。
- Ralph Loop：當 agent 嘗試結束 session 時，由 hook 攔截並重新注入 prompt 到乾淨 context，從 filesystem 讀取前次狀態繼續。
核心方向是從 single session agent 走向 multi-session agent。
Hooks 與 AGENTS.md
「我告訴 agent」不等於「系統強制執行」。
Hooks 是系統強制層：
- 每次 edit 後跑 typecheck / lint / test。
- 阻擋
rm -rf、git push --force、DROP TABLE。 - 開 PR 或 push main 前需要人工 approval gate。
- 成功時安靜，失敗時把錯誤詳細注入回迴圈。
AGENTS.md 是最高槓桿配置點：
- 保持短小。
- 遵守 ratchet 原則。
- 把真實失敗轉成明確規則。
- 記住 MCP 安裝即信任，任何 MCP server 都可能 prompt-inject。
Harness 不會消失，只會移動
每個 harness 元件都代表一個假設：模型自己做不到什麼。
隨著模型能力提升，某些 harness 功能會被模型吸收；但新的需求會把 harness 推到其他地方。
模型與 harness 會形成訓練飛輪：
- 模型在某個 harness 中使用。
- 使用 trace 回饋到 post-training。
- 新模型在同一 harness 下表現更好。
- Harness 再被調整以支援更高階行為。
從 LLM API 到 Harness Runtime
未來 agent 平台會從「呼叫模型 API」走向「harness runtime」。
方向包括：
- Parallel Multi-Agent：多個 agent 同時在同一 codebase 協作。
- Self-Improving Harness：agent 分析自己的 trace，找出 harness 層失敗並修復。
- JIT Harness Assembly：依任務即時組裝正確工具與 context，從靜態 config 走向動態編譯器。
頂尖 coding agents 會越來越像彼此；它們的差異不只在模型，而在外層 runtime。
Key Takeaway
今日模型「能做什麼」與你實際「看到它做什麼」之間的落差，很大一部分是 harness gap。
改進 agent 的實用路線：
- 把失敗視為信號。
- 收斂成短規則。
- 用 hook 強制執行。
- 把驗證結果接回迴圈。
- 管理 context，而不是無限制塞資料。
- 從 behaviour 設計 harness，而不是從功能清單開始。
Agent engineering 的本質不是「找一個更強模型」而已，而是持續收緊模型周圍的系統。