Harness Engineering

AI Agent 就像一台沒有方向盤的跑車——動力驚人卻難以上路。Harness Engineering 不優化模型本身，而是設計模型的「運行環境」：讓一個能力強大但可能犯迷糊的 AI，在你設計的系統結構下穩定輸出。核心公式：Model（智能）+ Harness（控制環境）= Reliable Agent（可信賴的 Agent）。

• Context Anxiety（語境焦慮）
  模型在對話快到 token 上限時，會察覺到「快沒空間了」，開始急著草率結束任務，品質斷崖式下滑——即使任務只完成了一半。
  e.g. 你叫 Claude 寫一個完整的 API 文件，寫到一半突然開始省略欄位、跳過範例，因為 Context 快滿了。
• Self-evaluation Leniency（自我感覺良好）
  讓同一個模型既當「生產者」又當「品質審查員」，它會不自覺地幫自己的輸出打高分、忽略明顯的邏輯錯誤，如同叫學生自己批改自己的考卷。
  e.g. 你問 GPT-4「這段 Code 有沒有問題？」，它說「整體邏輯是正確的」——但實際上有一個 null pointer dereference。
• Harness 的定位
  不修改模型權重，而是透過設計「運行環境」來補足缺陷：約束邊界、驗證機制、工作流控制、記憶體管理。
  e.g. AGENTS.md 告訴 Agent「這個專案只用 Next.js，認證用 NextAuth，不能引入 Redux」——Agent 便在這個邊界內發揮，而不是亂加套件。

OpenAI Codex 實踐：用 Harness 系統讓 Agent 自主產生超過 100 萬行程式碼，幾乎零人工手寫。問題的關鍵不是模型不夠聰明，而是之前沒有完善的 Harness 讓它可靠運作。

一套完整的 Harness 由三根支柱撐起，形成閉環系統：Context Engineering（提供正確資訊）→ Architectural Constraints（強制遵守規則）→ Feedback Loops（即時驗證修正）→ 再回到提供正確資訊。缺少任何一環，Agent 的輸出品質都會快速退化。

• Context Engineering（上下文工程）
  讓 Agent 在每次啟動時，都能「看見」完整正確的專案狀態，而不是摸黑工作。就像新員工第一天上班：你給他完整的 SOP 文件、現有系統架構圖、過去的設計決策，他才能做出符合期待的工作。
  e.g. 在 AGENTS.md 裡寫明：「認證系統在 /lib/auth，不要重新發明；資料庫用 Prisma ORM，Schema 在 /prisma/schema.prisma；所有 API 路由放在 /app/api」——Agent 啟動時自動讀取，就不會亂建檔案。
• Architectural Constraints（架構約束）
  Agent 如果沒有邊界限制，會傾向「走最短路徑」——可能把所有邏輯塞進一個檔案、引入不必要的依賴、違反你的目錄結構。Constraints 就是用 Linter、CI 規則等機械手段強制執行架構紀律。
  e.g. 設定 ESLint 規則：禁止 import "moment"（因為專案用 date-fns）、禁止在 Server Component 裡用 useState。Agent 寫錯就在 Pre-commit hook 被擋下，並得到明確的錯誤訊息告知原因。
• Feedback Loops（反饋迴路）
  讓 Agent 能「看到」自己輸出的結果，根據測試失敗或 lint 錯誤進行迭代修正，而不是一次性輸出一堆未驗證的程式碼。
  e.g. TDD for Agents：先讓 Agent 寫好測試（describe 預期行為），再實作 Code。Agent 執行測試 → Red → 修 Code → Green，就像一個真正的 TDD 開發流程，但完全自動完成。

三個模組的關係：Context 給 Agent「地圖」，Constraints 給 Agent「路障」，Feedback 讓 Agent「知道走錯了」。OpenAI 的研究顯示，有完整閉環的 Agent 系統，程式碼品質提升約 40%，需要人工介入的比例從 60% 降至 12%。

建 Harness 的最重要心法：「每次 Agent 犯錯，那個錯就必須變成永久防護」。你的工作不是修 Code 結果，而是修 Harness——讓同樣的錯誤在設計上永遠不可能再發生。人類負責決定 What（做什麼）和 Why（為什麼這樣做），Agent 負責 How（具體怎麼實作）。

• 人類負責 What & Why，Agent 負責 How
  如果你把「如何實作」的細節也指定死，換一個情境就會失效；但如果你清楚定義「我要什麼」和「這樣做的理由」，Agent 在任何情況下都能做出符合意圖的決策。
  e.g. 你說：「我需要使用者認證（What），因為這個應用有多帳號隔離需求（Why），請用 NextAuth 並確保 session 存在 HTTPOnly Cookie 中（Constraint）。」Agent 自行決定 JWT 要放哪些欄位、middleware 怎麼寫（How）。你不指定 How，但你鎖死了 What 和邊界。
• 每次錯誤都要成為永久防護
  如果只修結果，同樣的問題下次 Agent 會再犯一次；如果每次錯誤都轉化成規則或測試，Harness 會隨著時間變得越來越強壯，Agent 的行為也越來越可預期。
  e.g. Agent 生成了一個沒有處理錯誤邊界的 API Route → 你發現後，加一條 ESLint rule：「所有 API Route 必須有 try/catch 並回傳標準化的 error response」→ 下次這個問題就在 Pre-commit 階段直接被擋掉，不需要你再手動 Review。
• 可觀測性第一（Observability First）
  如果你看不見 Agent 在做什麼，就無法發現問題所在。當 Agent 連續跑幾小時都沒輸出，你需要知道它是卡在哪一步——是 Context 讀取失敗？還是測試一直紅燈無法收斂？
  e.g. 使用 進度追蹤檔案（如 PROGRESS.md）：Agent 每完成一個 Sprint，就寫入「已完成：登入頁面；待完成：Google OAuth；目前問題：redirect_uri 不符」。這樣你隨時都可以監看進度，也方便下一個 Agent 接手。

從小開始：在你的 Cursor 或 Claude Code 專案裡建一個 AGENTS.md，寫清楚「禁止做什麼」（技術棧限制）、「目錄結構是什麼」、「測試在哪裡跑」。這是最小可行的 Harness，但已經能讓 Agent 的穩定度大幅提升。

個人專案用的 Harness 跟企業級的設計差異很大。核心視角轉換：不再是「如何管理人」，而是「如何設計控制系統（Control System）」。最大的挑戰是多 Agent 協作下的長時任務管理——如何確保跑了 8 小時的 Agent pipeline 不會中途「失憶」或產生互相矛盾的輸出。

• Level 1 — 個人小專案
  起點不必複雜。一個寫得好的 AGENTS.md + 一套基本的自動化測試，就能讓單一 Agent 的行為穩定許多。重點是讓 Agent 在啟動就清楚知道：專案在做什麼、技術棧是什麼、哪些地方絕對不能改。
  e.g. AGENTS.md 第一段：「這是一個用 Next.js 14 + Supabase 的個人部落格。資料庫 Schema 在 /supabase/schema.sql，不要用 ORM。所有頁面 Server Component 為主，只有 Interactive UI 用 Client Component。」
• Level 2 — 團隊協作
  多人共用同一套 Harness，需要「共識層」：統一的知識庫格式、統一的驗收標準、統一的 CI 規範。否則每個人帶著自己的 AGENTS.md，Agent 在不同環境下產生互相矛盾的架構。
  e.g. 用 monorepo 管理所有 AGENTS.md 和 constraint rules，並在 CI Pipeline 中強制執行。任何對 Harness 規則的修改都需要 PR Review，確保整個團隊對「Agent 被允許做什麼」達成共識。
• Level 3 — 多 Agent 長時協作
  當多個 Agent（Planner / Generator / Evaluator）接力跑幾小時的任務，最大的風險是「中途失憶」——某個 Agent 忘記了先前的決策，產生結構性矛盾的輸出。解法是用「進度 Artifact」做狀態持久化。
  e.g. Planner Agent 產出 SPRINT.md（定義本次要做什麼、驗收標準是什麼）→ Generator Agent 讀取後實作，完成後更新 PROGRESS.md → Evaluator Agent 讀取兩份文件，對照測試結果評分 → 下一輪 Planner 從 PROGRESS.md 繼續。任何 Agent 在任何時間點都可以掉線重啟，狀態不會遺失。

OpenAI 的 Codex 企業應用：Planner Agent 設定架構 → Generator Agent 在隔離環境寫 Code → Evaluator Agent 跑 Playwright 自動化測試 + UI 截圖比對。三個 Agent 輪流接力，自主運行 8-12 小時，產出具備 React frontend、FastAPI backend、PostgreSQL 的完整應用，期間幾乎不需要人工介入。

工程師的工作重心正在從「寫程式」轉移到「設計讓 AI 能可靠寫程式的環境」。這不是失業，而是升級：你的價值從「實作細節」轉移到「架構設計、意圖定義、系統思維」。三個層次的 AI 工程從低到高依序是：Prompt Engineering → Context Engineering → Harness Engineering。

• 三層工程能力的進化
  Prompt Engineering 是最初階的介入——你告訴 AI「現在做什麼」；Context Engineering 是中階——你提供 AI 完整的背景知識讓它不出錯；Harness Engineering 是高階——你設計整個 AI 運作的生態系統，使其長期自主且可靠。
  e.g. 同一個任務「建立登入系統」： 初階：「請寫一個 Next.js 的登入頁面」 中階：「這是專案 README 和現有的 auth 模組，請在不違反現有架構的前提下加入登入功能」 高階：在 Harness 裡定義好 auth domain 的邊界、測試規格、依賴規則，讓 Agent 自主完成整個功能包含測試、文件、PR 描述。
• 自主性與安全性的黃金平衡
  給 Agent 太多自由：它會產生創意但風險高的解法，破壞你的架構；限制太多：它變成一個只能填模板的工具，失去 AI 的核心價值。Harness 的藝術就是找到這個平衡點——在「重要邊界」強制執行，在「實作細節」給予完全自由。
  e.g. 強制約束的邊界：不能刪除生產資料庫資料、不能修改認證邏輯、不能引入未審核的 npm 套件。給予完全自由的空間：UI 元件的實作方式、演算法的選擇、測試的撰寫風格——只要通過測試和 lint 就行。
• 2026 年的就業市場現實
  目前開發者中使用 AI 輔助的比例超過 80%，但將完整功能完全委派給 Agent 的比例不到 20%。造成這個差距的核心原因，就是缺乏 Harness。會建 Harness 的工程師，能把自己的 AI 同事變成真正可信的合作夥伴，生產力是普通工程師的 5-10 倍。
  e.g. 一個 AI 工程師的典型一天：早上定義 3 個 Sprint 和驗收條件 → 讓 3 個 Agent pipeline 並行跑 → 下午審核 PR、更新 Harness 規則 → 晚上啟動下一輪 Sprint。一個人實際上是 3-5 個 Agent 的「工程主管」。

最不會被取代的，是那些擅長「在 AI 混沌中建立秩序」的人。Harness Engineering 讓你從一個 Code Writer 進化成 System Architect——設計的不是程式，而是讓 AI 穩定產出程式的整套控制系統。這正是 AI 時代最有價值的工程師能力。