Agent Harness Engineering

資料來源#

• An open-source spec for Codex orchestration: Symphony.
• Anthropic's Boris Cherny: Why Coding Is Solved, and What Comes Next
• Effective harnesses for long-running agents
• Full Walkthrough: Workflow for AI Coding — Matt Pocock
• Harness engineering: leveraging Codex in an agent-first world
• How Anthropic's product team moves faster than anyone else | Cat Wu (Head of Product, Claude Code)
• Tips & Best Practices
• Tutorial: Team Telegram Assistant

摘要#

Agent Harness Engineering 是一門設計環境、產物和回饋迴圈的學科，使 AI 程式撰寫 agent 能夠在多個 context window 中進行可靠且持續的工作。核心轉變在於：工程師的工作從編寫程式碼，轉向建立使 agent 發揮功效的 harness 鷹架——指定意圖、結構化 context window、強制執行不變量以及建置驗證流水線。

細節#

根本問題#

AI 程式撰寫 agent 在具有限制 context window 的獨立 session 中工作。每個新的 session 開始時都沒有先前工作的記憶。若沒有刻意的 harness 設計，agent 會表現出可預測的失敗模式：

1. One-shotting — 企圖一次建置所有內容，在實作中途耗盡 context window，留下半成品且未記錄的工作
2. Premature victory — 看到部分進度就宣稱工作完成
3. Dirty state — 讓環境殘留 bug、未提交的變更或未記錄的進度，留給下一個 session 去整理
4. Incomplete verification — 在沒有進行端到端測試的情況下，將功能標記為已完成

雙 Agent 架構 (Anthropic)#

Anthropic 針對 Claude Agent SDK 的解決方案使用兩個專門的 system prompt：

• Initializer agent（僅限第一個 session）：搭建環境——編寫 init.sh 腳本、建立 claude-progress.txt 紀錄檔、生成一個將所有需求標記為「失敗」的結構化 JSON 功能列表，並進行初始的 git 提交。
• Coding agent（後續的每個 session）：讀取進度紀錄和 git 歷史記錄、執行基本的冒煙測試、挑選單一功能進行實作、進行端到端驗證（例如，針對 Web 應用程式透過 Puppeteer MCP）、提交乾淨的狀態，並更新進度檔案。

JSON 功能列表至關重要：agent 被指示絕不能刪除或編輯功能描述，只能在驗證後將 passes 從 false 改為 true。選擇 JSON 而非 markdown 是因為 agent 較不容易意外覆寫結構化的 JSON。

儲存庫作為記錄系統 (OpenAI)#

OpenAI 的 Codex 團隊在完全沒有手寫程式碼的情況下建置了一款產品（約 100 萬行程式碼、約 1,500 個 PR，3 至 7 名工程師花費 5 個月）。他們關鍵的架構洞察是：儲存庫本地端且有版本控制的產物是 agent 唯一能看見的內容——任何存在於 Slack、Google Docs 或人們腦袋中的東西都是隱形的。

他們的方法：

• 以 AGENTS.md 作為目錄，而非百科全書：一個指向更深層文件的簡短（約 100 行）地圖。單一龐大的說明檔案會失敗，因為它會擠佔任務 context window、當每件事都很「重要」時就變得毫無指導作用、極易過時，且難以進行機械式驗證。
• 漸進式揭露：agent 從一個小而穩定的進入點開始，並被教導要在何處深入探究。設計文件、執行計畫和技術債都在儲存庫中進行版本控制。
• 機械式強制執行：自訂的 linter（本身也是由 agent 生成的）強制執行架構——包含層與層之間的依賴方向、結構化日誌、命名規範、檔案大小限制。Lint 錯誤訊息被編寫為修復指引，並注入到 agent 的 context window 中。
• 文件園藝（Doc gardening）：一個定期運行的背景 agent 會掃描過時的文件並開啟修復 PR。

大規模強制執行架構#

上述兩個來源都收斂到一個關鍵原則：強制執行不變量，而非實作。定義嚴格的邊界（層級依賴關係、邊界處的資料驗證、命名規範），並讓 agent 在這些邊界內自由發揮。

OpenAI 針對每個業務領域使用嚴格的分層架構：Types → Config → Repo → Service → Runtime → UI，而橫切關注點則透過單一的 Providers 介面引入。這透過結構化測試和自訂 linter 來強制執行。他們指出，這種程度的架構嚴謹性通常會被推遲到擁有數百名工程師時才進行——但對於 agent 來說，這是一個早期先決條件，因為約束能夠在不產生偏差的前提下提升速度。

持續的熵管理#

Agent 生成的程式碼庫會累積熵：agent 會複製已經存在的模式，包括那些次優的模式。OpenAI 最初花費了 20% 的工程時間在手動清理「AI 廢料（AI slop）」。他們的解決方案：將「黃金原則」編碼進儲存庫中，並以定期節奏運行背景 agent 任務來掃描偏差、更新品質評級，並開啟針對性的重構 PR。這就像垃圾回收一樣運作——以微小的增量持續償還技術債，而不是讓它利滾利地複利累積。

Harness 即服務#

上述模式描述了單次 session 的 harness。兩個 2026 年的系統展示了自然的演進——作為服務持續運行的 harness，並具備每租戶的工作空間隔離：

• Symphony (OpenAI, 2026 年 3 月) — 長時間運行的常駐程式（daemon）輪詢 Linear、每個 issue 獨立的工作空間、每個 ticket 獨立的 Codex App Server session。這是由撰寫上述 OpenAI 資料來源的同一個團隊所開發；也是他們明確的「harness 即服務」迭代。Orchestrator 擁有工作空間生命週期、重試／退避（retry/backoff）、停滯偵測（stall detection）和協調（reconciliation）；儲存庫內的 WORKFLOW.md 是策略檔案。
• Hermes Agent (Nous Research) — Hermes Gateway 作為 systemd 或 launchd 運行；每位使用者獨立的 session 隔離；允許清單 + DM 配對授權；cron 工作傳送到指定的 Home 頻道。

兩者的收斂設計選擇：

1. 常駐程式優先部署（Daemon-first deployment） — 長時間運行的服務，而非每次呼叫的 CLI。
2. 每租戶工作空間隔離 — 每個 issue（Symphony）或每位使用者（Hermes）。
3. 以容器後端作為信任邊界（Docker、Singularity、Modal、Daytona），而非每次命令都要核准提示。Hermes 在「容器即安全邊界」的原則下，明確禁用了容器後端下的危險命令檢查。
4. 以儲存庫版本控制的 markdown 作為 control plane — Symphony 使用 WORKFLOW.md，Hermes 使用 AGENTS.md/SOUL.md，這與 session 層級的 CLAUDE.md/AGENTS.md 目錄規範模式相同。
5. 預設無持久化的 orchestrator 資料庫 — Symphony 明確選擇 tracker + 檔案系統來進行重啟復原；Hermes Gateway 狀態僅儲存於檔案系統中。

Symphony 的演進深化了上述原則。他們的第一個版本將 agent 視為僵化的狀態機節點——Codex 僅被要求實作 ticket 中的任務。當模型的能力成長到足以「建立多個 PR，並讀取檢閱回饋並加以解決」時，他們發現這太過限制，因而轉向給予 agent 目標 + 工具，而非狀態轉移。這是在編排層（orchestration layer）應用的「強制執行不變量，而非實作」（參見 Ticket-Driven Agent Orchestration）。

對於 orchestrator 與 coding agent 之間的整合邊界，Symphony 採用 Codex App Server Protocol——透過 stdio 進行 JSON-RPC，並支援連續回合（continuation turns）與動態 tool calls——這使得協定契約明確且具備版本相容性。該協定的動態 tool calls功能也是一個顯著的 harness 原語：由 orchestrator 實作的工具可以封裝 subagent 絕不應該看見的憑證（例如，Symphony 的 linear_graphql 工具代理了經過驗證的 GraphQL，而無需將 Linear 的存取權杖給予 subagent 容器）。

人類的角色#

在這兩個系統中，人類在不同的抽象層工作：

• 排定工作優先順序，並將使用者回饋轉化為驗收準則
• 設計環境與回饋迴圈
• 驗證結果並提供品味與判斷
• 當 agent 遇到困難時，診斷缺少了什麼能力（工具、護欄、文件）並將其回饋給系統——始終透過 agent 進行，而非直接編寫程式碼

相關連結#

• LLM-as-Compiler Knowledge Base — 共享了儲存庫本地端知識作為記錄系統、增量編譯以及 LLM 維護產物的模式
• Claude Code Best Practices — 許多 harness 工程原則在 Claude Code 環境中的實際應用（CLAUDE.md、skills、hooks、subagents）
• LLM-Driven Vulnerability Research — 漏洞尋找鷹架是一個極簡的 harness：隔離的容器、單一 prompt、具有檔案評級預處理和驗證 agent 的 agentic 迴圈
• Client-Side Agent Optimization — harness 提供了執行基底，用戶端最佳化器隨後透過組合選擇進行調優；harness 強制執行的不變量約束了 AgentOpt 搜尋的空間
• Scale-Dependent Prompt Sensitivity — 輸出長度不變量（透過系統 prompt、schema 或驗證器）是 harness 層級對規模相關過度思考的緩解措施——符合「強制執行不變量，而非實作」的原則
• Claude Code Auto Mode — 基於分類器的 tool-call 門控是在權限邊界「機械式強制執行不變量」的具體實例——在執行前強制執行破壞性操作限制，而非透過建議性 prompt
• Claude Opus 4.7 — 更好的檔案系統記憶增強了將儲存庫本地端且有版本控制的產物作為 agent 記憶的理由；任務預算呼應了 harness 已經施加的明確資源信封規範
• Symphony — 來自同一個 OpenAI 團隊的自然「harness 即服務」演進；以 ticket 為單位和每個 issue 獨立的工作空間是此處建立的 harness 模式的直接延伸
• Ticket-Driven Agent Orchestration — 編排層對「強制執行不變量，而非實作」的重新闡述；一旦單次 session 的 harness 開始運作，下一個瓶頸就是下一個要運行哪個 session
• Codex App Server Protocol — 讓「harness 即服務」成為可能的整合邊界；orchestrator 透過有版本控制的 JSON-RPC 契約驅動 session，而不是去解析 CLI
• Hermes Agent — 平行的常駐程式優先 agent 生態系統；採用每位使用者而非每個 issue 的隔離，並使用相同的容器後端安全模式；有界的 MEMORY.md/USER.md 檔案實作了明確的記憶信封
• Context Window Smart Zone — 促使系統 prompt 極簡化、以 AGENTS.md 作為目錄以及在全新上下文中進行檢閱者規範的底層約束；二次方注意力縮放設定了每個 harness 運作的預算
• Agent Loop Pattern — 一旦單次 session 的 harness 運作後，自然的 session 層級原語：AFK 消化 Kanban 待辦事項，將工作碎片化為許多全新上下文的迭代
• Vertical Slice Tracer Bullets — 規劃層對「強制執行不變量，而非實作」的重新闡述——不變量是「每個切片都會產生可見的回饋」
• Design Concept Grilling — 對齊層的 harness 原語；透過強制執行計畫前訪談來防止過早生成計畫
• Deep Modules for Agents — 程式碼庫形狀的互補：在深層模組（deep-module）程式碼庫中的 agent 可以節省 smart-zone token，並具有自然的測試邊界
• Harness Shrinkage as Models Improve — harness 與模型之間的分工：prompt 鷹架隨著模型改進而縮減，但機械式驗證仍然發揮關鍵作用
• Model Introspection Feedback — 偵錯時工具：詢問模型失敗的原因，修復 harness，而不是模型
• Interaction Models — 在 互動 層（即時影音）將 harness 對決模型的問題堅定地轉向模型解決；VAD／輪次檢測／對話管理 harness 溶解為模型行為（Thinking Machines Lab, 2026 年 5 月）
• The Bitter Lesson — 「強制執行不變量，而非實作」背後的原則：不要用人工設計那些會被規模化通用能力所包容的內容
• Interaction / Background Model Split — 相同的多 agent 拆分，但是針對 時間 關注點（保持響應性 vs. 深度思考）而非上下文隔離；harness 與模型分工在互動層的實例
• MCP and Computer Use — 連接器是 非 harness 基底；模型決定使用哪一個；隨著模型做出更好的選擇，圍繞工具分派決策的 harness 邏輯將會縮減
• Agent Context Files — 「強制執行不變量，而非實作」的建議性那一半：CLAUDE.md/AGENTS.md/WORKFLOW.md 是 policy plane；hook 和 orchestrator 不變量是機械式的那一半

衍生內容#

• Opus 4.6 → 4.7 Changes and Multi-Agent Coding Considerations — 將「強制執行不變量，而非實作」和 Writer/Reviewer 模式應用於 Opus 4.7 多 agent 程式撰寫團隊

相關連結#

• Agent-Native Infrastructure — 建立 agent 可解讀的環境是 基礎設施 層的 harness 工程；Karpathy 的「先向 agent 描述它」與以 AGENTS.md 作為目錄是相同的直覺
• AI-Driven Formal Proof Search — AlphaProof Nexus 的 proof-sketch-with-EVOLVE-BLOCK-markers 是一個為定理證明「強制執行不變量，而非實作」的 harness（agent 僅能編輯標記區域；定理陳述是不變量）

未決問題#

• 單一通用型程式撰寫 agent 的表現是否優於具有專門測試、QA 和清理 agent 的多 agent 架構？
• 在完全由 agent 生成的系統中，架構的一致性在數年內會如何演進？
• 在何種程式碼庫規模下，以 AGENTS.md 作為目錄的方法需要被更複雜的上下文路由所取代？
• 這些聚焦於 Web 應用程式的發現，在多大程度上可以推廣到其他領域（科學研究、金融建模）？

資料來源#

• Harness engineering: leveraging Codex in an agent-first world
• Effective harnesses for long-running agents