你將學到什麼

本指南涵蓋了從基本原理到實際應用的 Harness Engineering。你將了解它是什麼、為什麼 OpenAI 將其最大的內部專案押注於此、使其發揮作用的特定架構模式，以及如何將這些原則應用於你自己的 AI agent 工作流中——無論你使用的是 Codex、Claude Code、OpenCode 還是任何其他 agent 系統。

Harness Engineering：2026年 AI Agent 開發完全指南

如果說 2025 年是 AI agents 證明其具備編寫代碼能力的年份，那麼 2026 年就是我們意識到 agent 本身並非難點——Harness 才是關鍵 的一年。

OpenAI 的 Codex 團隊在 2026 年 2 月發布了一篇里程碑式的部落格文章，描述了他們如何構建一個包含約 1,000,000 行代碼的生產級應用程式，而其中沒有任何一行代碼是由人類親手編寫的。其秘訣並不在於更好的模型或更聰明的提示詞，而是在於他們圍繞 agent 構建的系統——Harness（治理工程/開發架構）。Source

本指南將解析該實驗中出現的每一項原則、模式和實踐技術，以及隨之興起的更廣泛的 Harness Engineering 運動。

第一部分：什麼是 Harness Engineering？

定義

Harness Engineering 是一門設計完整環境的學科——包含腳手架、回饋迴圈、文件、架構限制和機器可讀的產出物——這使得 AI coding agents 能夠在最少的人為干預下，大規模地進行可靠、高品質的工作。

「Harness」一詞源自馬具：韁繩、馬鞍、馬嚼子——這是一套完整的設備，用於將強大但不可預測的動物導向正確的方向。一匹失控的馬是危險的。而一匹套上 Harness 的馬則建立了文明。這同樣適用於 AI agents。Source

為什麼它在現在興起

從提示工程（prompt engineering）向 Harness Engineering 的轉變反映了 AI 開發領域的成熟：

Source

推動這一轉變的關鍵見解是：agents 的能力已經強大到瓶頸從模型品質轉向了環境品質。一個在結構混亂的 repository 中運作的世界頂尖模型，其產出結果會比一個在 Harness 環境良好的環境中運作的中等模型更差。

第二部分：OpenAI Codex 實驗

規模

在一個為期 5 個月的內部實驗中，OpenAI 工程師構建並發布了一個包含約 1,000,000 行代碼的測試版產品。該 repository 涵蓋了應用邏輯、基礎設施、工具、文件和內部開發公用程式。系統中不存在任何預先存在的人類編寫代碼。Source

團隊

專案初期僅由 3 名工程師驅動 Codex。在 5 個月內，大約有 1,500 個 pull requests 被提交並合併。當團隊增加到 7 名工程師時，產出效率反而增加了——這是一個違反直覺的結果，表明 Harness 本身是主要的生產力倍增器，而非個人技能。

OpenAI 估計，他們構建該系統所花費的時間大約僅為手動編寫代碼所需時間的 1/10。Source

初始腳手架

專案始於 Codex CLI 使用 GPT-5 生成初始腳手架，並由一小組現有模板引導：

• Repository 結構和目錄規範
• CI/CD 配置
• 代碼格式化和 linting 規則
• 套件管理器設定
• 應用框架樣板

從這個種子開始，其他一切都通過 agent 驅動的開發而成長。

週五問題

在實驗早期，團隊發現了一個關鍵問題：他們每週五都要花費 20% 的工程時間來清理他們稱之為「AI 廢料（AI slop）」的東西。這包括不一致的模式、重複的邏輯、命名錯誤的變數以及架構偏移（architectural drift）。

這無法規模化。解決方案是將他們的標準編碼到 Harness 本身中，以便 agents 從一開始就產出更乾淨的結果，並針對殘餘的偏移構建自動化清理系統。

第三部分：五大核心原則

原則 1：儲存庫優先知識

從 agent 的角度來看，任何它在執行時無法在 context 中訪問的東西，實際上都是不存在的。存在於 Google Docs、聊天記錄、Slack 訊息或人們大腦中的知識對系統來說是隱形的。

這意味著所有知識必須作為 repository 本地的、具備版本的產出物存在：

• 代碼 — 主要產出物
• Markdown 文件 — 架構決策、規範、入職指南
• Schemas — API 合約、資料庫 schemas、類型定義
• 可執行計畫 — agent 可以遵循的逐步任務分解
• 配置 — linter 規則、CI 管道、格式化標準

團隊了解到，隨著時間的推移，他們需要將越來越多的 context 放入 repo 中。每當 agent 因為缺乏 context 而出錯時，修復方法不是更好的提示詞，而是將該 context 添加到 repository 中。Source

實際應用：

# ARCHITECTURE.md (位於 repo 根目錄)

## 依賴規則
- UI 組件可以從 Service 層匯入，但絕不能從 Repo 層匯入
- Service 層不得從 Runtime 層匯入
- 所有跨網域通訊均通過類型化的事件總線進行

## 命名規範
- React 組件：PascalCase，結尾標註用途 (UserListPage, UserCard)
- Services：camelCase，結尾標註 Service (userService, authService)
- Types：PascalCase，開頭標註網域 (UserProfile, OrderItem)

## 測試要求
- 所有 Service 函數都需要單元測試
- 所有 API 端點都需要整合測試
- 覆蓋率閾值：每個套件 80%

原則 2：黃金原則

黃金原則是直接編碼到 repository 中的具有立場的機械化規則，使代碼庫對於未來的 agent 執行保持易讀和一致。它們不是願景指南，而是強制性的限制。

來自 OpenAI 實驗的例子：

1. 偏好共用工具套件而非手動編寫的輔助函式 — 集中不變量，以便在需要更改行為時，只需在一個地方更改。
2. 不要以 YOLO 風格探測數據 — 驗證邊界或依賴類型化的 SDK，使 agents 不會意外地基於猜測的數據形狀進行構建。
3. 一個概念，一個檔案 — 每個檔案應代表一個單一概念，使 agents 更容易找到並修改正確的位置。
4. 顯式優於隱式 — 避免那些需要 agent 具備部落知識才能理解的神奇行為。

Source

這些原則不僅僅是文件。它們通過以下方式強制執行：

• Linter 規則 — 自定義 linters（本身由 Codex 生成）會標記違規行為。
• 結構化測試 — 驗證架構合規性的測試。
• CI 閘門 — 違反黃金原則的 pull requests 會被自動拒絕。

原則 3：具有機械化強制執行力的分層架構

OpenAI 專案中的每個業務網域都被劃分為一組固定的層級，並具有嚴格驗證的依賴方向：

Types → Config → Repo → Service → Runtime → UI

依賴關係僅向一個方向流動。UI 組件可以依賴於 Runtime 和 Service，但 Service 絕不能從 UI 匯入。Repo 可以依賴於 Config 和 Types，但絕不能依賴於 Service。Source

這些限制是通過機械化方式強制執行的：

// structural-test.ts — 強制執行依賴邊界
import { analyzeImports } from './tools/import-analyzer';

describe('Dependency Layer Enforcement', () => {
  it('Service layer must not import from Runtime', () => {
    const violations = analyzeImports({
      sourceLayer: 'service',
      forbiddenLayers: ['runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });

  it('Repo layer must not import from Service', () => {
    const violations = analyzeImports({
      sourceLayer: 'repo',
      forbiddenLayers: ['service', 'runtime', 'ui'],
    });
    expect(violations).toEqual([]);
  });
});

結構化測試驗證合規性並防止違反模組化分層。這不是建議——它是 CI 強制執行的。每個 pull request，無論是由人類還是 agent 創建，都必須通過這些測試。

原則 4：自動化垃圾回收

即使有黃金原則和結構化強制執行，agent 生成的代碼也會隨時間產生偏移。OpenAI 團隊通過實施自動化垃圾回收解決了這個問題——這是定期運行的背景任務：

1. 掃描整個代碼庫中偏離黃金原則的地方。
2. 更新品質等級，根據合規性分數為每個模組評分。
3. 開啟針對性的重構 pull requests，以修復特定類別的偏移。

這用一個持續運行的系統取代了手動的「週五清理」。垃圾回收器本身由 Codex agents 驅動，形成了一個自我維護的迴圈。Source

# .github/workflows/garbage-collection.yml
name: Codebase Garbage Collection
on:
  schedule:
    - cron: '0 2 * * *'  # 每天凌晨 2 點運行

jobs:
  gc-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run golden principle scanner
        run: npx codex-gc scan --principles ./GOLDEN_PRINCIPLES.md
      - name: Generate refactoring PRs
        run: npx codex-gc fix --auto-pr --max-prs 5

原則 5：可執行的計畫

在 agents 編寫代碼之前，它們先編寫計畫。這些計畫不是非正式的筆記——它們是結構化的、可執行的文件，規定了：

• 目標：任務完成後要達到的目的。
• 要修改的檔案：agent 將接觸的檔案顯式列表。
• 依賴關係：此工作依賴的其他任務或模組。
• 驗收標準：如何驗證工作已完成。
• 限制條件：絕不能違反的架構規則。

# 計畫：添加用戶通知偏好設定

## 目標
允許用戶配置他們接收提醒的通知管道（電子郵件、簡訊、推送），並具有針對每個類別的細粒度控制。

## 要修改的檔案
- src/types/user.ts — 添加 NotificationPreferences 類型
- src/repo/userRepo.ts — 添加 getPreferences/setPreferences 方法
- src/service/notificationService.ts — 根據偏好過濾通知
- src/ui/pages/SettingsPage.tsx — 添加偏好設定 UI 區塊

## 限制條件
- 必須遵循 Types → Repo → Service → UI 依賴流
- NotificationPreferences 類型必須共用，不可重複
- 所有新方法都需要單元測試

## 驗收標準
- [ ] 用戶可以針對每個通知類別切換 電子郵件/簡訊/推送
- [ ] 偏好設定在不同會話間保持持久化
- [ ] 關閉某個管道後，30 秒內停止在該管道發送通知

計畫作為 markdown 檔案存在於 repository 中，受到版本控制，並且可以在執行前進行審查——這為人類在意圖和實作之間提供了一個檢查點。

第四部分：Codex Agent 迴圈

了解 Codex agent 迴圈如何在 Harness 中運作對於有效的 Harness Engineering 至關重要。

迴圈架構

OpenAI 在其配套部落格文章 "Unrolling the Codex agent loop" 中發布了 Codex agent 迴圈的詳細分解。Source 該迴圈遵循以下週期：

讀取 Context → 計畫 → 執行 → 驗證 → 提交 (或重試)

每次迭代：

1. 讀取 Context：agent 從 repository 中讀取相關檔案、文件、schemas 和任務計畫。
2. 計畫：根據 context，agent 決定要做哪些更改。
3. 執行：agent 編寫或修改代碼。
4. 驗證：Harness 針對更改運行測試、linters 和結構化檢查。
5. 提交或重試：如果驗證通過，agent 提交代碼。如果失敗，agent 讀取錯誤輸出並重試。

Harness 的作用是讓第 1 步和第 4 步盡可能包含豐富的信息。agent 讀取的 context 越多，其計畫就越好。驗證回饋越具體，它收斂到可行解決方案的速度就越快。

App Server Harness

在他們的文章 "Unlocking the Codex harness: how we built the App Server" 中，OpenAI 描述了驅動 agent 迴圈的具體基礎設施。Source App Server 提供：

• 為每個 agent 任務提供 沙盒執行環境。
• 預配置的工具訪問權限 (檔案系統、終端機、瀏覽器)。
• 從 repository 產出物中進行 自動 context 注入。
• 串流式驗證回饋，以便 agents 可以實時看到測試失敗情況。

第五部分：將 Harness Engineering 應用於你的團隊

快速入門：最小可行 Harness

你不需要複製 OpenAI 的整個基礎設施就能從 Harness Engineering 中獲益。從這些基礎元素開始：

第 1 步：創建 ARCHITECTURE.md

在 repository 根目錄以機器可讀的格式記錄專案的架構規則。包括：

• 模組邊界和允許的依賴關係
• 命名規範
• 檔案組織規則
• 測試要求

這個單一檔案能顯著提高 agent 的輸出品質，因為 agents 在進行更改前會閱讀它。

第 2 步：添加結構化測試

編寫驗證架構規則的測試。這些測試不檢查業務邏輯——它們檢查代碼組織是否正確：

// service 檔案不應從 UI 模組匯入
test('service layer isolation', () => {
  const serviceFiles = glob('src/services/**/*.ts');
  for (const file of serviceFiles) {
    const imports = extractImports(file);
    const uiImports = imports.filter(i => i.startsWith('../ui/'));
    expect(uiImports).toHaveLength(0);
  }
});

第 3 步：配置 CI 驗證

確保你的 CI 管道對每個 pull request（包括由 agents 創建的）運行結構化測試、linters 和類型檢查。agent 應該看到與人類開發者相同的驗證輸出。

第 4 步：在 Agent 執行前編寫任務計畫

在要求 agent 實作功能之前，先編寫一份結構化的計畫文件，具體說明要修改的檔案、要遵循的限制條件以及驗收標準。將這些計畫儲存在你的 repository 中。

第 5 步：設定自動化清理

實施每週或每晚運行的 CI 任務，掃描代碼庫中偏離文件標準的地方，並創建專注於重構的 PRs。

選擇你的 Agent 系統

無論你使用哪種 agent，Harness Engineering 原則都適用：

Harness 存在於你的 repository 中，而非 agent 中。這意味著你可以切換 agents 而不會損失在 Harness 上的投入。

從一個 Agent 擴展到多個

OpenAI 的實驗證明了 Harness Engineering 可以實現並行的 agent 執行。由於 Harness 強制執行了架構邊界，多個 agents 可以同時在代碼庫的不同部分工作而不會產生衝突。

並行 agent 執行的關鍵要求：

1. 明確的模組所有權 — 每個 agent 在定義的邊界內工作。
2. 模組間的類型化介面 — agents 可以針對介面編寫代碼，而無需了解實作細節。
3. 防止合併衝突 — 任務範圍經過界定，以盡量減少檔案重疊。
4. 集中化驗證 — 所有 agents 都提交到同一個 CI 管道。

第六部分：常見陷阱與反模式

反模式 1：將 Agent 當作 Harness

agent 並不是 Harness。Harness 是 agent 運作的環境。要求一個更聰明的模型來補償結構混亂的 repository 是錯誤的方法。應該修復環境，而不是提示詞。

反模式 2：文件放在錯誤的地方

如果你的架構決策存在於 Confluence、Notion 或 Google Docs 中，agents 無法看到它們。修復方法很簡單但需要紀律：將所有與開發相關的文件移入 repository 中。

反模式 3：手動清理而非自動化強制執行

如果你花費大量時間清理 agent 生成的代碼，你需要更好的強制執行機制，而不是更多的清理會議。每個重複發生的清理任務都應該變成 linter 規則、結構化測試或自動化重構任務。

反模式 4：過度約束

過於僵化的 Harness 會阻礙 agents 尋找創意解決方案。目標是約束架構，而不是實作。告訴 agents 他們可以修改哪些模組以及允許哪些依賴，但讓他們決定如何在這些邊界內實作邏輯。

反模式 5：無視 Agent 的回饋

當一個 agent 在某些任務上反覆失敗時，失敗通常預示著 Harness 存在漏洞，而非 agent 的局限性。追蹤失敗模式，並利用它們來改進你的文件、結構化測試或架構限制。

第七部分：Harness Engineering 的未來

Martin Fowler 的觀點

Martin Fowler 在其部落格上發布了對 Harness Engineering 的分析，指出它代表了軟體團隊運作方式的根本轉變。這門學科借鑒了幾十年來的軟體工程最佳實踐——持續整合、架構決策記錄、依賴注入——但為了 agent 驅動的世界對其進行了重新定位。Source

HumanLayer 框架

HumanLayer 團隊發布了分析報告，將 Harness Engineering 稱為一種「能力問題（skill issue）」——認為設計有效 Harness 的能力將成為高效工程團隊與落後團隊之間的主要差異化因素。Source

這對開發者意味著什麼

Harness Engineering 並不會取代開發者的技能，而是重新引導它。資深工程師不再編寫代碼，而是設計能讓 agents 編寫好代碼的系統。重要的技能從實作轉向架構，從編碼轉向系統設計，從編寫測試轉向設計測試框架。

對於構建應用程式的團隊，像 ZBuild 這樣的平台已經將 Harness Engineering 原則納入其應用構建工作流中。ZBuild 不要求開發者從頭開始設計自己的 Harness，而是提供預配置的架構模式、依賴管理和驗證系統，引導 AI agents 產出高品質結果——讓開發者專注於產品決策而非基礎設施。

三個階段

展望未來，Harness Engineering 可能會經歷三個階段：

1. 短期 (2026)：團隊採用儲存庫優先的文件、結構化測試和黃金原則。對於具備良好 Harness 的專案，agent 輔助開發成為標準實踐。

2. 中期 (2027)：Harness 生成本身變得由 agent 驅動。agents 分析現有代碼庫，並根據觀察到的模式提出 Harness 配置建議——linter 規則、結構化測試、依賴邊界。

3. 長期 (2028+)：Harness 變為自適應。它們不再是靜態規則，而是根據 agent 生成代碼的結果進行演進，在 agents 頻繁出錯的區域自動收緊限制，在他們持續成功的區域放寬限制。

第八部分：實踐清單

使用此清單評估你團隊的 Harness Engineering 成熟度：

基礎 (從這裡開始)

• Repository 根目錄存在 ARCHITECTURE.md
• 代碼格式化已自動化 (Prettier, Black, gofmt)
• Linting 在每個 pull request 上運行
• 強制執行類型檢查 (TypeScript strict, mypy 等)

中級

• 結構化測試驗證依賴邊界
• 黃金原則已記錄且可由機器強制執行
• 在 agent 執行前編寫任務計畫
• Agent 生成的 PRs 經過與人類 PRs 相同的 CI 流程

高級

• 定期運行自動化垃圾回收
• 多個 agents 可以並行工作而無衝突
• 追蹤 agent 失敗模式並用於改進 Harness
• Harness 本身受到版本控制並像代碼一樣進行審查

專家級

• Agents 生成 Harness 的部分內容 (linter 規則, 結構化測試)
• 自動為每個模組分配品質等級
• 基於 agent 成功率進行數據驅動的 Harness 改進
• 團隊每位工程師每週交付的代碼量比採用 agents 前更多

結論

Harness Engineering 並非曇花一現。它是軟體工程在 AI agents 足以編寫生產代碼但需要結構化環境才能做好的時代下的自然演進。OpenAI 的百萬行代碼實驗在大規模規模上證明了這一概念，而他們闡述的原則——儲存庫優先知識、黃金原則、分層架構、自動化垃圾回收和可執行計畫——適用於任何規模的團隊。

在 2026 年掌握 Harness Engineering 的團隊將比那些將 AI agents 視為高級自動補全的團隊交付更快、維持更高的代碼品質，並更有效地擴大規模。agent 是馬。Harness 則是使其發揮作用的關鍵。

來源

• Harness Engineering: Leveraging Codex in an Agent-First World — OpenAI
• Unlocking the Codex Harness: How We Built the App Server — OpenAI
• Unrolling the Codex Agent Loop — OpenAI
• OpenAI Introduces Harness Engineering — InfoQ
• Harness Engineering — Martin Fowler
• Skill Issue: Harness Engineering for Coding Agents — HumanLayer
• From Prompt Engineering to Harness Engineering — SoftmaxData
• How to Build an Agent Harness — Study Notes
• Harness Engineering — GTCode
• OpenAI Harness Engineering: Ship 1M Lines of Code — The Neuron
• How OpenAI Built 1M Lines of Code Using Only Agents — TonyLee
• Harness Engineering — The New Discipline — CodeNote