2026 年 2 月 11 日，OpenAI 發了一篇工程部落格叫 Harness Engineering: Leveraging Codex in an Agent-First World。
它不是在講「怎麼寫更好的 prompt」，而是在回答一個更根本的問題：
當 AI 的產碼能力近乎免費，軟體工程的本質會往哪裡移動？
TL;DR
- OpenAI 用 3 人團隊 + Codex，從空 repo 出發，五個月交付 100 萬行程式碼、1500 個 PR，0 行手寫 code
- 他們發現瓶頸不是模型能力，而是 環境規格不足——缺工具、缺護欄、缺回饋迴圈
- 這套方法論叫 Harness Engineering（韁繩工程）：把軟體開發變成一個閉環控制系統，人類設計環境，agent 執行交付
- 本文會用三層深度拆解這篇文章：底層邏輯 → 機制分析 → 應用框架，並穿插我實際用 Claude Code 協作開發的第一手經驗
一、底層邏輯：為什麼需要 Harness Engineering
1.1 真正的稀缺資源不是 code，是人類注意力
整篇文章的起點只有一句話：Humans steer. Agents execute.
當 Codex 可以單次 run 持續 6 小時、人類睡覺它還在跑時，「寫 code」這件事已經不是瓶頸。真正的瓶頸變成：你怎麼確保它做對了、做得一致、做得可維護？
這就是為什麼他們把工程師的角色重新定義為：設計環境、指定意圖、打造回饋迴圈——而不是打字。
1.2 它本質上是一個控制系統
如果你把整篇文章讀完，會發現它一直在繞同一個架構：
┌─────────────────────────────────────────────────────┐
│ 閉環控制系統 │
│ │
│ 狀態（State） │
│ └─ repo 裡的 code + docs + plans + schema │
│ │
│ 感測器（Sensors） │
│ └─ UI 截圖、logs、metrics、traces、測試結果、錄影 │
│ │
│ 致動器（Actuators） │
│ └─ agent 用 gh / scripts / skills 改 code、開 PR、merge │
│ │
│ 控制器（Controller） │
│ └─ CI、linters、結構測試、品味規則、GC 清理任務 │
│ │
│ 人類 = 系統設計者，不是操作員 │
└─────────────────────────────────────────────────────┘
每個後續章節都是在補這個系統的某一塊。理解了這個框架，整篇文章的脈絡就清楚了。
1.3 「0 行手寫程式碼」不是噱頭，是逼出真相的實驗設計
他們用一個極端約束——包含應用邏輯、測試、CI、文件、observability、內部工具，通通由 Codex 寫——逼自己回答：「如果你不能親手修，你會怎麼建這個系統？」
結果：
| 指標 | 數值 |
|---|---|
| 起始時間 | 2025 年 8 月底，空 repo |
| 團隊 | 初期 3 人 → 後來 7 人（吞吐量反而上升） |
| 五個月產出 | ~100 萬行 code、~1500 PR |
| 平均吞吐量 | 3.5 PR / 人 / 天 |
| 單次 run 最長 | 6 小時+（人類睡覺中） |
| 預估效率 | 手寫時間的 1/10 |
這些數字不是在證明「模型很神」，而是在證明：如果你把環境做對，產出可以到達一個讓整個開發哲學被迫改變的量級。
二、機制分析：五大支柱逐一拆解
2.1 讓應用可被 agent 驗證（Application Legibility）
問題：吞吐量上來後，人類 QA 立刻變瓶頸。
他們怎麼解：不是加人做 QA，而是把 QA 能力做成 agent 的「感官」。
具體做了三件事：
a) 每個改動一個獨立可啟動的 app（per git worktree boot）
每個 git worktree 都能獨立 boot 一個 app 實例。等於每個 PR 自帶一個可驗證的沙盒世界。
b) 把瀏覽器變成 agent 的眼睛
接入 Chrome DevTools Protocol，做出 DOM snapshots、截圖、導航等 skills。Codex 能自己重現 bug、驗證修正、推理 UI 行為。
c) 把 observability 變成 agent 可查詢的訊號
每個 worktree 有一套 ephemeral（用完就拆）的本地 observability stack，agent 可用 LogQL 查 logs、PromQL 查 metrics。因此像 "startup < 800ms" 這種要求從口號變成可機械驗證的 acceptance criteria。
為什麼重要：沒有感官的 agent 只能寫「想像中的修復」；有感官的 agent 才能寫「可驗證的修復」。
我的實際經驗：我用 Claude Code 改過一個元件，它一直改錯。越來越不耐煩後我停下來想——它是不是根本看不到它需要看的東西？答案是對的：那個元件依賴另一個檔案的型別定義，AI 根本沒讀過那個檔案。它不是不聽話，它是瞎了一隻眼還被要求穿針。從那之後我的原則是：AI 卡住時，不催它 try harder，先問「它缺什麼感官？」
2.2 Repo 變成唯一真相來源（System of Record）
問題：context 是稀缺資源，怎麼給 agent 足夠資訊又不塞爆它？
他們踩過的坑：一個超大的 AGENTS.md，失敗原因四連發：
- Context 被擠掉：巨大規則檔擠掉任務本身、程式碼和關鍵 docs
- 太多規則 = 沒有規則：agent 變成局部 pattern-matching
- 會腐爛（rot）：變成陳舊規則墳場
- 難以機械驗證：coverage / freshness / ownership / cross-links 全靠人記
他們的解法：漸進揭露（Progressive Disclosure）
AGENTS.md 降格成目錄（約 100 行），只告訴 agent「去哪裡找真相」。真正的知識庫放在結構化 docs/：
AGENTS.md ← 地圖（~100 行）
ARCHITECTURE.md ← 架構邊界與依賴方向
docs/
├── design-docs/ ← 設計文件（含 core-beliefs.md）
├── exec-plans/ ← 執行計畫
│ ├── active/
│ ├── completed/
│ └── tech-debt-tracker.md
├── generated/ ← 程式生成的（如 db-schema.md）
├── product-specs/ ← 產品需求
├── references/ ← 外部參考（llms.txt 類）
├── DESIGN.md
├── FRONTEND.md
├── QUALITY_SCORE.md
├── RELIABILITY.md
└── SECURITY.md
更狠的是：他們用 dedicated linters + CI 驗證文件是否最新、互相 cross-link、結構正確。甚至有一個 doc-gardening agent 定期掃陳舊文件並自動開 PR 修正。
然後是那句最殘酷的真相：
從 agent 角度：跑的時候看不到的東西，等於不存在。 Google Docs、Slack 討論、人腦默契都不算。
我的實際經驗：我一開始也把所有規則塞進超長的 CLAUDE.md。結果 AI 開始選擇性失明——太多規則等於沒有規則。更慘的是規則互相打架：「要保持簡潔」vs「要寫完整的 error handling」，AI 在兩者間 random walk。改成「地圖 + 分層文件」後效果好非常多：prompt 只放當下必知（不超過一頁），其他的放 repo 裡需要時再叫 AI 去讀。
2.3 機械化架構執法（Architecture & Taste Invariants）
問題：文件不夠用。Agent 會複製 repo 既有模式——好的壞的都會。久了就 drift。
解法一：守邊界，不管細節
每個 business domain 固定分層，只允許「往前」依賴：
Types → Config → Repo → Service → Runtime → UI
跨域關注（auth / connectors / telemetry / feature flags）只能從單一明確介面 Providers 進入。其他路徑一律禁止，由 custom linters + structural tests 機械化執法。
他們點破一個反直覺的重點：這種架構你通常等到百人團隊才做；但有 coding agents 時，它是早期前置條件——因為「限制」才能換「速度而不腐爛」。
解法二：品味不變量（Taste Invariants）
一小組靜態強制的規則：structured logging、命名慣例、file size limits、platform reliability requirements。
最狠的一招：因為 lints 是客製的，他們把 lint error message 寫成可注入 agent context 的修正指引——不只說「你錯了」，還說「你應該改成什麼」。
解法三：守邊界但給自治
要求「邊界資料 shape 必須被 parse/validate」，但不指定怎麼做（agent 常選 Zod，但不是硬規定）。這是成熟的平台思維：邊界、正確性、可重現性要中央強制；邊界內怎麼寫，給自治。
我的實際經驗：用 AI 寫 code 的頭幾次，你會被產出速度震撼到。幾天後回頭看——命名不統一、重複 helper 散落各處、error handling 每個檔案都不一樣。AI 會複製 repo 既有模式，你的 repo 已經有三種 error handling 風格，它就隨機挑一種用。先建 linter 規則比事後補便宜十倍。
2.4 吞吐量改變 Merge 哲學
問題：當 agent 吞吐量遠大於人類注意力，傳統的重 gate、重審批、重阻塞會變反效果。
他們的做法：
- Minimal blocking merge gates
- PR 生命週期短
- Test flake 用後續 run 修，不無限卡死
- Review 從 human-to-agent 逐步推成 agent-to-agent
核心邏輯：corrections are cheap, waiting is expensive.
但他們也承認：在低吞吐環境這樣做會不負責任。這個哲學有前提——你的感測器和護欄必須先到位。
2.5 垃圾回收系統化（Entropy & GC）
問題：完全自治帶來必然的系統漂移。他們一開始每週五花 20% 時間人工清「AI slop」，不 scalable。
解法：把品味編碼成可機械執行的規則，再做週期性清理。
具體做了兩件事：
a) Golden Principles 寫進 repo
兩個例子：
- 偏好共用 utility packages，不要到處手刻 helper（集中不變量）
- 不要 YOLO 探資料 shape——在邊界做驗證或依賴 typed SDK
b) 背景 GC 任務
定期掃 deviation、更新 quality grades、開 refactor PR。多數 PR 一分鐘內可 review 並 automerge。
他們用一句比喻收斂：技術債像高利貸——小步連續還款，比一次爆炸式重構好。 人類品味被捕捉一次，然後持續強制在每一行 code 上。
我的實際經驗：我也幹過「週五清 AI slop」的事。後來改成每週叫 AI 掃一遍 codebase 找不一致的模式（「列出來，不要改」），效果好很多。重點是把「還債」從偶發行為變成固定流程。
三、這套方法論背後的幾個深層洞察
3.1 Harness Engineering ≠ Context Engineering
這是社群裡最熱的辯論之一。
Context Engineering 關注：給 AI 什麼資訊？ — few-shot、RAG、system prompt 設計。
Harness Engineering 關注：AI 在什麼結構中運作？ — 護欄、回饋迴圈、架構約束、可觀測性。
| 面向 | Context Engineering | Harness Engineering |
|---|---|---|
| 比喻 | 給新人一份完美的 onboarding 文件 | 確保辦公室有門禁、CI/CD、on-call |
| 解決什麼 | 「這次任務做對」 | 「長期不腐爛」 |
| 失敗模式 | 單次錯誤 → context 問題 | 漸進式漂移 → harness 問題 |
| 投資回報 | 線性（每次任務都要做） | 複利（一次建、持續收益） |
兩者不衝突，但多數人只在做第一件事。
我的體感：花 1 小時設計完美 prompt 的效益，遠不如花 1 小時設好 ESLint + TypeScript strict mode + pre-commit hook。前者下次任務就過期了，後者每次 AI 產出都會被檢查。
3.2 技術選型被翻轉：「AI-friendliness」成為正經維度
OpenAI 偏好「boring technology」——可組合、API 穩定、訓練集常見——因為 agent 更容易建模。他們甚至寧可讓 agent 自己重寫 p-limit 的功能子集（緊密整合 OpenTelemetry、100% test coverage），也不要依賴不透明的外部套件。
我的實際經驗：AI 處理 React + Tailwind 穩如老狗（訓練資料裡到處都是）；處理某個小眾 UI 庫則是災難（會「創造性猜測」API）。AI 寫 SQL 比寫 ORM 特定語法穩定，因為 SQL 是 universal boring tech。選技術棧時，「AI 寫起來會不會出事」正在變成真正的評估維度。
3.3 「Agent-generated」的範圍比你想的大
他們不是只讓 agent 寫 feature code，而是repo 內所有東西：
- 產品 code + tests
- CI + release tooling
- 內部開發工具
- 文件與設計歷史
- Evaluation harnesses
- Review comments 與回覆
- 管 repo 的 scripts
- Production dashboard definition files
這重新定義了「agent-generated」的邊界。它不是「AI 幫你寫寫 function」，而是「AI 營運整個 repo」。
3.4 自主性門檻：單一 prompt 端到端交付
他們的 repo 最近跨過一個門檻。Codex 可以用單一 prompt 做到：
- 驗證現況
- 重現 bug
- 錄影展示失敗
- 修 bug
- Drive app 驗證
- 再錄影展示修好
- 開 PR、回應 agent/人類 feedback
- 偵測並修 build failures
- 只有需要 judgment 才升級給人
- Merge
但他們也強調：這高度依賴 repo 的結構與工具投資，不能假設泛化。
四、誠實的批判：它沒說的事
4.1 空 repo 的奢侈
他們從零開始。現實中多數人面對的是有幾萬行 code、三種 error handling 模式、兩套 CSS 方案的 legacy codebase。在既有專案上做 Harness Engineering 的難度遠高於從零開始。
4.2 功能正確性的驗證缺口
Martin Fowler 在他的分析中直接點出：文章專注 code quality 和 maintainability，但對行為是否正確著墨不多。AI 寫的 code 可以通過所有 lint、型別檢查、甚至單元測試——但需求理解錯了，一切都是白搭。
4.3 模型差距是真的
OpenAI 用 GPT-5 + Codex，地球上最強的 coding agent 基礎設施之一。一般團隊用其他模型，效果不會一樣。好消息是 Harness Engineering 的原則是模型無關的——差別只在「agent 能做到多少自動化」。
4.4 「修正比等待便宜」需要前提
Fast merge 的前提是你的感測器和護欄已經到位。沒有 CI、沒有 lint、沒有型別檢查就放快 merge？那不叫 agile，那叫自殺。
4.5 多年尺度仍是未知數
他們自己也承認：五個月的實驗不能回答「fully agent-generated 系統在多年尺度下架構一致性會怎麼演化」。這仍是開放問題。
五、應用框架：你今天就能開始做的事
不需要 Codex、不需要 GPT-5、不需要一整個團隊。以下按投資報酬率排序。
Level 1：護欄先行（投入 2 小時，立即見效）
做什麼：把 linter 和 type check 當成 AI 的第一道防線。
# 這不只是給人用的，這是 AI 的護欄
npx eslint . --fix
npx tsc --noEmit
為什麼有效：每次 AI 產出 code，這些工具會自動告訴它「哪裡不對」。如果你能自訂 lint 規則，把 error message 寫成修正指引（「不要用 X，改用 Y，原因見 docs/decisions/003.md」），效果再翻一倍。
OpenAI 對應：custom linters + error messages 注入 agent context。
Level 2：地圖而非百科全書（投入 30 分鐘）
做什麼：寫一份 100 行以內的 CLAUDE.md / AGENTS.md，只做導航。
# 這個專案是什麼
一句話描述。
# 技術棧
- Next.js 15 + TypeScript + Tailwind
- MDX for blog posts
# 檔案結構重點
- components/：UI 元件
- content/blog/：部落格文章（.mdx）
- lib/：工具函式
# 規則（只放最重要的 3-5 條）
- 所有元件用 TypeScript，不准 any
- 樣式用 Tailwind，不用 CSS modules
# 需要更多 context 時去哪裡找
- 架構決策：docs/decisions/
- 部署設定：vercel.json
- 前端規範：docs/FRONTEND.md
為什麼有效：AI 拿到地圖就知道去哪裡找真相，不會被一堆規則淹沒也不會因為缺資訊而亂猜。
OpenAI 對應：AGENTS.md ~100 行作為目錄，真正知識放 docs/。
Level 3：決策寫進 repo（每個決策 10 分鐘）
做什麼：重要的架構決策寫成 markdown，commit 進 repo。
docs/decisions/
├── 001-why-nextjs.md
├── 002-tailwind-over-css-modules.md
└── 003-mdx-for-blog-posts.md
每個檔案三段：決策是什麼、為什麼這樣選、考慮過但放棄的替代方案。
為什麼有效：AI 不會「好心」幫你重構成它覺得更好的方式，然後把你精心設計的 trade-off 全毀。它讀到「我們因為 X 原因選了 A 而非 B」，就不會去動搖這個決定。
OpenAI 對應：docs/design-docs/ + exec-plans/ + core-beliefs.md。
Level 4：讓 AI 能驗證自己的產出（投入 1-3 小時）
做什麼：確保測試能一鍵跑完，而且 AI 知道怎麼跑。
# AI 能執行這個，看到哪些測試過了、哪些沒過
npm test
進階版：加上 Playwright 做 E2E 測試，讓 AI 能操作 UI 驗證行為。
為什麼有效：AI 只能「寫」code 但不能「驗」code → 你得用自己的眼睛當 QA → 你就是瓶頸。給 AI 驗證能力，瓶頸就從「人類注意力」移到「測試覆蓋率」——後者是可以系統性提升的。
OpenAI 對應：per-worktree boot + Chrome DevTools Protocol + ephemeral observability stack。
Level 5：週期性品質掃描（每週 15 分鐘）
做什麼：固定頻率讓 AI 掃 codebase 找不一致。
看一下 components/ 目錄，找出：
1. 命名不一致的元件
2. 重複的邏輯
3. 缺少 TypeScript 型別的地方
列出來，不要改。
先列問題、再決定要不要修。這比「自動修」安全，也比「不管它」好無限倍。
為什麼有效：技術債是高利貸。小步連續還，比等到爆炸再處理便宜。把「還債」從偶發行為變成固定流程，就不會累積到不可收拾。
OpenAI 對應：golden principles + 背景 GC 任務 + quality grades。
Level 6：架構邊界機械化（投入半天，適合中大型專案）
做什麼：定義模組間的依賴方向，用工具強制執行。
# 例如：不允許 UI 層直接 import Service 層的內部實作
# 跨域只能走指定的 Provider 介面
可以用 ESLint 的 import/no-restricted-paths、或 dependency-cruiser 這類工具。
為什麼有效：這是 OpenAI 說的「限制才能換速度而不腐爛」。沒有這些邊界，AI 產出越多，架構越亂；有了邊界，AI 在安全的範圍內可以全速跑。
OpenAI 對應：Types → Config → Repo → Service → Runtime → UI 固定分層 + custom structural tests。
六、一張圖總結：Harness Engineering 的投資階梯
投資少 ────────────────────────────────────── 投資多
效果立即 ──────────────────────────────────── 效果長期
Level 1 Level 2 Level 3 Level 4 Level 5 Level 6
護欄先行 → 地圖導航 → 決策版本化 → 驗證閉環 → 品質 GC → 架構邊界
ESLint CLAUDE.md docs/ npm test 週掃描 依賴方向
TypeScript ~100 行 decisions/ Playwright 找不一致 機械化執法
Prettier 不是百科 三段式 AI 能跑 先列不改 限制換速度
[今天就做] [今天就做] [本週開始] [下週開始] [每週維持] [規模夠再做]
七、結語：紀律在腳手架，不在每一行 code
OpenAI 在文章最後寫了一句很漂亮的話：
軟體仍然需要紀律，但紀律越來越表現在 scaffolding（腳手架），而不是每一行 code。
我的理解是：Harness Engineering 不是什麼高深的新理論。它是把軟體工程的基本功——型別系統、linting、CI、文件、架構設計——重新理解為「給 AI 的工作環境」。
你不需要 100 萬行 code 的專案才能開始。你只需要問自己一個問題：
如果明天有個新人加入你的專案（那個新人是 AI），他能只靠 repo 裡的東西就開始有效工作嗎？
如果答案是「不行」，那你現在就知道該投資什麼了。
而且你已經有了路線圖：從 Level 1 開始，一層一層加上去。每一層都會讓你的 AI 協作效率有感提升——不是因為模型變強了，而是因為你給它的環境變好了。