Harness Engineering：構建讓 AI Agent 真正發揮作用的系統完全指南

2026 年 3 月 —— 如果說 2025 年是 AI 代理證明自己可以編寫代碼的一年，那麼 2026 年就是我們意識到 Agent（代理）本身並非難點 —— Harness（駕馭系統）才是關鍵。

OpenAI 的 Codex 團隊剛剛構建了一個擁有 超過 100 萬行代碼 的生產級應用，其中 零行代碼是由人手編寫的。工程師們沒有寫代碼，而是設計了讓 AI 能夠可靠地編寫代碼的系統。那個系統 —— 包含約束、回饋迴路、文檔、Linter 和生命週期管理 —— 就是業界現在所稱的 Harness（駕馭工程/護具工程）。

Harness 工程 是設計這些系統的新興學科。它正在改變軟件工程師的定義。

---

什麼是 Harness 工程？

馬具的比喻

「Harness」一詞源自馬具 —— 韁繩、馬鞍、馬嚼子 —— 這一整套用於引導強大但不可預測的動物朝正確方向前進的裝備。這個比喻是有意為之的：

• 馬 是 AI 模型 —— 強大、快速，但它不知道自己該去哪裡。
• Harness（馬具/駕馭系統） 是基礎設施 —— 將模型的能量轉化為生產力的約束、護欄和回饋迴路。
• 騎手 是人類工程師 —— 提供方向，而非親自奔跑。

沒有 Harness，AI 代理就像荒野中的純種馬。速度極快，令人印象深刻，但對於完成任何工作都毫無用處。

正式定義

Harness 工程 是指設計並實施具備以下功能的系統：

1. 約束 (Constrain)：限制 AI 代理的行為（架構邊界、依賴規則）。
2. 告知 (Inform)：告知代理應該做什麼（上下文工程、文檔）。
3. 驗證 (Verify)：確認代理操作正確（測試、Linting、CI 驗證）。
4. 糾正 (Correct)：在代理出錯時進行修復（回饋迴路、自我修復機制）。

Martin Fowler 將其描述為 「我們可以用來約束 AI 代理的工具和實踐」 —— 但它不僅僅是為了安全。一個好的 Harness 能讓代理變得 更有能力，而不僅僅是被控制。

---

為什麼 Harness 工程在現在至關重要

模型已成為商品，Harness 才是護城河

這是 AI 行業正在面臨的一個尷尬事實：底層模型的重要性不如其周圍的系統。

LangChain 明確證明了這一點。他們的編碼代理在 Terminal Bench 2.0 上的表現從 52.8% 提升到了 66.5% —— 排名從 前 30 名躍升至前 5 名 —— 過程中沒有對模型做任何改動。他們只更改了 Harness：

變更項目	具體做法	影響
自我驗證迴路	增加了完成前的檢查清單中間件	在提交前攔截錯誤
上下文工程	在啟動時映射目錄結構	代理從一開始就理解代碼庫
迴路檢測	追蹤重複的文件編輯	防止「死循環（Doom loops）」
推理三明治法	高推理用於規劃/驗證，中等推理用於實施	在時間預算內獲得更好的質量

同樣的模型。不同的 Harness。結果大幅提升。

OpenAI 的 100 萬行代碼證明

OpenAI 的實驗是迄今為止最有力的證據：

• 5 個月 的開發時間。
• 最終產品中包含 100 萬行以上代碼。
• 零行人工手寫代碼 —— 每一行都是由 Codex 代理生成的。
• 開發時間約為人工的 1/10。
• 該產品擁有 內部日常用戶和外部 Alpha 測試人員。
• 它能 發布、部署、出錯並被修復 —— 統統由 Harness 內的代理完成。

工程師的工作是什麼？設計 Harness。指定意圖。提供回饋。而不是寫代碼。

---

Harness 工程的三大支柱

OpenAI 的框架將 Harness 工程分為三個核心類別：

1. 上下文工程 (Context Engineering)

上下文工程旨在確保代理在正確的時間獲得正確的信息。

靜態上下文：

• 本地存儲庫文檔（架構規範、API 契約、風格指南）。
• 編碼了項目特定規則的 AGENTS.md 或 CLAUDE.md 文件。
• 由 Linter 驗證的交叉鏈接設計文檔。

動態上下文：

• 代理可訪問的可觀測性數據（日誌、指標、追蹤）。
• 代理啟動時的目錄結構映射。
• CI/CD 流水線狀態和測試結果。

關鍵規則： 從代理的角度來看，任何它無法在上下文中訪問的東西都不存在。存放在 Google Docs、Slack 頻道或人們腦袋裡的知識對系統來說是不可見的。存儲庫必須是唯一的真理來源（Single Source of Truth）。

2. 架構約束 (Architectural Constraints)

這是 Harness 工程與傳統 AI 提示詞工程（Prompting）區別最大的地方。你不再只是告訴代理「寫出好的代碼」，而是 通過機械手段強制執行好代碼的標準。

依賴分層：

Types → Config → Repo → Service → Runtime → UI

每一層只能從其左側的層級導入。這不是建議 —— 而是通過結構化測試和 CI 驗證強制執行的。

約束執行工具：

• 確定性 Linter —— 自動標記違規行為的自定義規則。
• 基於 LLM 的審計代理 —— 審查其他代理代碼是否符合架構規範的代理。
• 結構化測試 —— 類似 ArchUnit，但針對 AI 生成的代碼。
• Pre-commit 鉤子 —— 在代碼提交前進行自動檢查。

為什麼約束能提高輸出質量： 矛盾的是，縮小解決方案空間反而會讓代理 更有生產力。當代理可以生成任何東西時，它會浪費 Token 在死胡同裡徘徊。當 Harness 定義了清晰的邊界，代理能更快地收斂到正確的解決方案。

3. 熵管理（「垃圾回收」）

這是最被低估的組件。隨著時間推移，AI 生成的代碼庫會積累熵（Entropy）—— 文檔與現實脫節、命名慣例出現偏差、死代碼累積。

Harness 工程通過 定期的清理代理 來解決這個問題：

• 文檔一致性代理 —— 驗證文檔是否與當前代碼匹配。
• 約束違規掃描器 —— 查找繞過早期檢查的代碼。
• 模式執行代理 —— 識別並修復偏離既定模式的行為。
• 依賴審計器 —— 追蹤並解決循環依賴或不必要的依賴。

這些代理按計劃運行 —— 每日、每週或由特定事件觸發 —— 保持代碼庫對人類審查者和未來的 AI 代理都是健康的。

---

Harness 工程實踐：團隊如何運作

OpenAI 模式：零人工代碼

OpenAI 的 Harness 工程團隊結構：

角色	傳統模式	Harness 工程模式
編寫代碼	主要工作	從不
設計架構	工作的一部分	主要工作
編寫文檔	事後補充	關鍵基礎設施
評審 PR	代碼審查	評審代理輸出 + Harness 有效性
調試	閱讀代碼	分析代理行為模式
測試	編寫測試	設計代理執行的測試策略

Stripe 模式：大規模小助手 (Minions)

Stripe 內部的編碼代理（稱為 Minions）現在 每週生成超過 1,000 個已合併的 Pull Request：

1. 開發者在 Slack 中發布任務。
2. Minion 編寫代碼。
3. Minion 通過 CI。
4. Minion 開啟 PR。
5. 人類進行評審並合併。

在第 1 步和第 5 步之間沒有開發者交互。Harness 處理了一切 —— 測試執行、CI 驗證、風格合規性和文檔更新。

LangChain 模式：中間件優先

LangChain 將他們的 Harness 結構化為可組合的中間件層：

Agent 請求
  → LocalContextMiddleware (映射代碼庫)
  → LoopDetectionMiddleware (防止重複)
  → ReasoningSandwichMiddleware (優化計算)
  → PreCompletionChecklistMiddleware (強制驗證)
  → Agent 回應

每個中間件層都在不修改核心代理邏輯的情況下添加了特定功能。這種模組化方法使 Harness 可測試且可進化。

---

構建你的第一個 Harness：實用框架

第一階段：基礎 Harness（個人開發者）

如果你在個人項目中使用 Claude Code、Cursor 或 Codex：

設置清單：

• 包含項目慣例的 CLAUDE.md 或 .cursorrules 文件。
• 用於 Lint 和格式化的 Pre-commit 鉤子。
• 代理可以運行以進行自我驗證的測試套件。
• 清晰且命名一致的目錄結構。

設置時間： 1-2 小時 影響： 防止最常見的代理錯誤。

第二階段：團隊 Harness（小型團隊）

針對共享代碼庫的 3-10 人開發團隊：

在第一階段基礎上增加：

• 包含團隊範圍慣例的 AGENTS.md。
• 由 CI 強制執行的架構約束。
• 用於常見任務的共享提示詞模板。
• 由 Linter 驗證的「文檔即代碼」。
• 專門針對代理生成 PR 的代碼審核清單。

設置時間： 1-2 天 影響： 確保全隊代理行為一致。

第三階段：生產級 Harness（工程組織）

針對運行數十個並行代理的組織：

在第二階段基礎上增加：

• 自定義中間件層（迴路檢測、推理優化）。
• 可觀測性集成（代理閱讀日誌和指標）。
• 定期運行的熵管理代理。
• Harness 版本控制和 A/B 測試。
• 代理性能監控儀表板。
• 代理卡住時的呈報政策。

設置時間： 1-2 週 影響： 代理作為自主貢獻者運作。

---

常見的 Harness 工程錯誤

1. 過度設計控制流

「如果你過度設計控制流，下一次模型更新就會弄斷你的系統。」

模型進步很快。2024 年需要複雜流水線的功能，現在可能只需要一個上下文窗口提示詞。構建你的 Harness 要具備 可拆卸性 —— 當模型變得足夠聰明而不再需要「聰明」的邏輯時，你應該能夠移除它。

2. 將 Harness 視為靜態

Harness 需要隨模型一起進化。當新模型版本提高了推理能力時，你的推理優化中間件可能會適得其反。每逢重大模型更新，都要審查並更新 Harness 組件。

3. 忽略文檔層

最有影響力的 Harness 改進通常是最簡單的：更好的文檔。如果你的 AGENTS.md 含糊不清，你的代理輸出也會含糊不清。投入精力編寫精確、機器可讀的文檔，作為代理的真理來源。

4. 缺乏回饋迴路

沒有回饋的 Harness 是一個籠子，而不是導引。代理需要知道它何時成功，何時失敗。內置以下功能：

• 任務完成前的自我驗證步驟。
• 將測試執行作為代理工作流的一部分。
• 按任務類型統計代理成功率。

5. 僅供人類閱讀的文檔

如果你的架構決策存在於人們的腦海中或代理無法訪問的 Confluence 頁面中，那麼 Harness 就存在漏洞。代理需要的一切都必須在存儲庫中。

---

Harness 工程與相關概念的對比

概念	範疇	核心關注點
提示工程 (Prompt Engineering)	單次交互	撰寫有效的提示詞
上下文工程 (Context Engineering)	模型上下文窗口	模型看到哪些信息
Harness 工程 (Harness Engineering)	整個代理系統	環境、約束、回饋、生命週期
代理工程 (Agent Engineering)	代理架構	內部代理設計和路由
平台工程 (Platform Engineering)	基礎設施	部署、擴展、運維

Harness 工程 包含 了上下文工程，並借鑑了提示工程，但它在更高的層次上運作 —— 它關乎讓代理可靠的完整系統，而不僅僅是單次交互的輸入。

---

這對軟件工程師意味著什麼

職業生涯正在改變

Harness 工程代表了軟件工程師職責的真正演變：

以前	以後
寫代碼	設計讓 AI 寫代碼的環境
調試代碼	調試代理行為
評審代碼	評審代理輸出 + Harness 有效性
編寫測試	設計測試策略
維護文檔	構建作為機器可讀基礎設施的文檔

這並不意味著工程師的技術含量降低了。相反，Harness 工程需要 更深層次 的架構思考 —— 你正在設計即使沒有你的持續干預也能運作的系統。

關鍵技能

根據我們在 NxCode 構建 AI 驅動產品的經驗：

1. 系統思維 —— 理解約束、回饋迴路和文檔如何相互作用。
2. 架構設計 —— 定義可執行且具生產力的邊界。
3. 規範撰寫 —— 將意圖表達得足夠精確，以便代理執行。
4. 可觀測性 —— 構建能揭示代理行為模式的監控。
5. 迭代速度 —— 快速測試和優化 Harness 配置。

我們的經驗：實踐中什麼最有效

我們一直在使用多個代理系統（Claude Code、Codex、Cursor）構建 AI 驅動的 Web 應用程序。對我們影響最大的模式包括：

• 存儲庫優先文檔：每個架構決策、命名慣例和部署流程都在存儲庫中。Slack 或 Google Docs 中不存放任何核心內容。
• 漸進式約束構建：從基礎 Lint 開始，隨著模式出現增加架構約束，不要試圖預先設計完美的 Harness。
• 代理專屬評審清單：AI 生成的代碼與人工代碼有不同的失敗模式。我們的評審過程會針對常見的代理模式（過度抽象、不必要的錯誤處理、文檔偏差）進行檢查。
• 多供應商 Harness 設計：我們的 Harness 可與 Claude、GPT 和 Gemini 模型協同工作。供應商中立的設計意味著我們可以更換模型而無需重建整個系統。

---

核心要點

1. Harness 工程是一門新學科，旨在設計使 AI 代理可靠的系統 —— 包括約束、回饋迴路、文檔和生命週期管理。
2. 模型是商品，Harness 是護城河 —— LangChain 僅通過更改 Harness 就在基準測試中從前 30 名躍升至前 5 名。
3. OpenAI 在零人工代碼下構建了 100 萬行以上的代碼 —— 證明了 Harness 工程在生產規模上的可行性。
4. 三大支柱：上下文工程、架構約束和熵管理。
5. 從簡單開始：一個好的 AGENTS.md 和 Pre-commit 鉤子比複雜的中間件更有影響力。
6. 工程師的角色正在演變 —— 從編寫代碼轉向設計 AI 寫代碼的環境。
7. 構建可拆卸的 Harness —— 當模型進步時，過度設計會失效；保持系統的可適應性。

---

相關資源

• Agentic Web 詳解：AGENTS.md, MCP 與 A2A —— Harness 工程構建其上的協議層
• Cursor Cloud Agents：虛擬機上的自主編碼 —— 實踐中的雲端代理 Harness
• Claude Code 遠程控制：終端移交指南 —— 遠程管理代理會話
• 使用 NxCode 構建您的網站 —— 採用多供應商 Harness 架構的 AI 驅動 Web 開發