OpenAI 這篇 Harness engineering: leveraging Codex in an agent-first world 蠻有料的，是內部團隊一個極端實驗的實戰報告: 從一個空的 git repo 開始，五個月寫出約一百萬行程式碼、開了 1,500 個 PR、做出真實有用戶在用的內部產品。三個工程師起步(後來七個)，每人每天平均 3.5 個 PR，他們估計比人工寫快了 10 倍。

最關鍵的限制條件: 工程師一行 code 都不寫，所有程式碼包含應用邏輯、測試、CI、文件、observability、內部工具，全部由 Codex 寫。

這篇真正值得讀的不是「AI 寫了多少 code」，而是他們把這套方法論命名成 harness engineering ── harness 字面意思是「馬具」，引申為「讓動力能拉動車子的那套裝備」。當寫 code 不再是工程師的核心工作，人類的價值轉移到打造那套讓 agent 能可靠工作的環境、工具、約束、回饋迴路。這篇就是在講要怎麼打造這套 harness。

小編幫大家整理了「要怎麼做才能改進你的 agent」這個視角下的具體做法。

1. 心態切換: 失敗了不是「再試一次」，而是「補哪個能力」

這是整篇文章最重要的思維轉換。團隊早期進度比預期慢，不是因為 Codex 不行，而是環境沒準備好 ── agent 缺少必要的工具、抽象層、內部結構。

當 Codex 任務失敗時，他們從不問「怎麼讓 prompt 更好」，而是問:

缺了什麼能力? 怎麼讓 agent 看得懂、做得到、且可被機械驗證?

然後讓 Codex 自己把這個能力補進 repo。這個迴路本身就是 harness engineering 的核心動作: 每次 agent 撞牆，就在 harness 上補一塊。久了 harness 越來越完整，agent 越來越能獨立工作。

小編覺得這點蠻關鍵: 大部分人遇到 agent 出錯第一反應是調 prompt 或換模型，但真正的槓桿在於改造它身處的「世界」。

2. 讓應用對 Agent 可讀: agent 看不到的東西等於不存在

當程式碼產出量暴增，瓶頸變成人類的 QA 能力。他們的核心策略是把更多東西做成 agent 可讀，具體做了這幾件事:

🔹 每個 git worktree 都能獨立啟動 app ── Codex 拿到任務後可以開一個自己的 instance，不會跟其他任務互相干擾。

🔹 接 Chrome DevTools Protocol 進 agent runtime ── 寫了 skills 讓 Codex 能截圖、操作 DOM、做頁面導航，因此能自己重現 bug、驗證修復、推理 UI 行為。

🔹 完整的本地 observability stack ── Logs、metrics、traces 都暴露給 Codex，可以用 LogQL 查 logs、PromQL 查 metrics、TraceQL 查 traces。每個 worktree 有自己 ephemeral 的觀測 stack，用完就丟。

有了這套，像「確保服務啟動小於 800ms」「這四個關鍵 user journey 任何一個 span 不能超過兩秒」這種 prompt 才變成 agent 可以實際處理的任務。團隊現在常看到單一 Codex 任務連續跑超過六小時(通常是人類睡覺的時候)。

編按: 這條原則用一句話講就是「From the agent’s point of view, anything it can’t access in-context while running effectively doesn’t exist.」── 從 agent 的角度看，它在執行時沒辦法 in-context 取得的東西，等於不存在。Slack 討論、Google Doc、人腦裡的默會知識，對 agent 來說都是黑洞。要讓 agent 強，就要把這些東西想辦法塞進 repo。

3. AGENTS.md 是目錄，不是百科全書

Context 管理是讓 agent 在大型複雜任務中有效的最大挑戰之一。團隊一開始用「一個大 AGENTS.md」的做法，失敗得很徹底。原因:

  • Context 是稀缺資源: 巨型指令文件擠掉真正的任務、code、相關 docs，agent 反而抓不到重點
  • 太多指導等於沒有指導: 當每件事都「重要」，沒有東西是重要的，agent 會退化成在局部 pattern matching
  • 它腐化得超快: 大文件變成過期規則的墓園，agent 分不出哪些還有效，最後變成「有吸引力的麻煩製造器」(attractive nuisance)
  • 無法驗證: 一坨文字無法做機械化檢查(覆蓋率、新鮮度、所有權、交叉引用)

他們的做法是把 AGENTS.md 當目錄(table of contents)用，控制在約 100 行，指向 docs/ 下結構化的知識庫:

docs/
├── design-docs/      # 設計文件 + core-beliefs.md
├── exec-plans/       # 執行計畫 (active/completed/) + tech-debt-tracker.md
├── product-specs/    # 產品規格
├── references/       # 第三方 library 的 llms.txt
└── DESIGN.md / FRONTEND.md / QUALITY_SCORE.md / RELIABILITY.md / SECURITY.md

關鍵詞是「漸進式揭露(progressive disclosure)」: agent 從一個小而穩定的入口進來，被教會去哪裡找下一層資訊，而不是一開始就被全部資訊淹沒。

而且這套文件結構是機械化強制執行的: 專屬的 linter 和 CI 驗證知識庫的時效性、交叉引用、結構正確性，還有一個定期跑的 “doc-gardening” agent 自動掃描過期文件並開 PR 修正。

4. 用「無聊」的技術，必要時讓 agent 自己重寫

因為整個 repo 是 agent 生成、優化目標是 agent 的可讀性(不是人類的)，他們的技術選型也跟著變:

  • 偏好「無聊」的技術 ── 組合性好、API 穩定、訓練資料裡有大量代表
  • 偏好可以完全在 repo 內被理解和驗證的依賴和抽象
  • 有時候讓 agent 重寫一個簡化版的 library，比繞過第三方 library 不透明的行為更便宜

舉例: 他們不用 p-limit 這類通用套件，而是讓 Codex 自己寫一個 map-with-concurrency helper ── 跟自己的 OpenTelemetry instrumentation 緊密整合、100% 測試覆蓋率、行為完全符合 runtime 預期。

這個取捨蠻反直覺的，但邏輯一致: agent 看不懂的依賴 = 風險，自己重寫雖然增加 code 量，但換來完全可控的行為。

5. 用機械化規則執行架構品味

光有文件不夠，文件約束不了一個產出極快的 agent。他們的做法是「強制不變量(invariants)，但不微管理實作」。

每個業務 domain 切成固定分層架構: Types → Config → Repo → Service → Runtime → UI，依賴方向嚴格驗證、跨領域關注(auth、telemetry、feature flags)只能透過唯一介面 Providers 進來。任何違反都被 custom linter 和結構測試擋下。

更妙的是這些 linter 也是 Codex 寫的，而且錯誤訊息會直接寫上修復指示，這樣下次 agent 撞到錯誤訊息就直接知道該怎麼改。

編按: 「parse, don’t validate」是他們強制的另一個品味 ── 在邊界把資料 parse 成型別，而不是用 if/else 驗證。模型自己愛用 Zod，他們沒指定但結果一致。具體做法可參考原文連結的 blog。

這種架構治理通常等到團隊有幾百人才會做，但在 agent-first 世界裡是早期必備: 因為約束才是讓速度不帶來腐化的關鍵。中央強制邊界，局部允許自由 ── 這跟管一個大型工程組織的 platform 部門很像。產出風格不一定符合人類偏好，但只要正確、可維護、對未來 agent 可讀就過關。

6. 從 throughput 反推: 重新設計 merge 流程

當 Codex 一天開出幾十個 PR，傳統工程習慣反而變成阻力。團隊的做法:

  • 最少的 blocking merge gates ── 不要讓 PR 卡很久
  • PR 都是短命的 ── 不搞長 branch
  • Test flake 用「再跑一次」處理 ── 而不是無限期 block 進度
  • 大部分 review 都是 agent-to-agent: Codex 自己 review 自己的 code，再請其他 agent reviewer 給意見，跑一個迴圈直到所有 agent reviewer 都滿意 ── 這個模式他們叫 Ralph Wiggum Loop

文章裡有句蠻坦白的話:「在低 throughput 環境這樣做是不負責任的，但在這裡通常是對的取捨。」邏輯是: agent throughput 遠超過人類注意力時，修正成本很便宜，但等待成本很貴。

7. 垃圾回收: 把品味寫成可機械執行的「黃金法則」

agent 會複製 repo 裡已有的 pattern，包括不好的。一開始團隊每週五花 20% 時間清理「AI slop」，但這完全不 scale。

後來改成把「golden principles」寫進 repo，例子:

  1. 偏好共用 utility package，不要手寫 helper(讓不變量集中)
  2. 不准 YOLO 式探測資料形狀 ── 在邊界驗證或用 typed SDK，agent 不能憑猜測的 shape 蓋東西

然後一組背景 Codex 任務定期掃描偏差、更新品質分數、開 refactoring PR。大部分一分鐘內就能 review 完並自動 merge。

這就像 GC: 技術債是高利貸，持續小額還款比累積到痛苦爆發好得多。人類的品味只需要捕捉一次，之後就在每一行 code 上自動執行。

自主性的天花板: end-to-end 跑完一個 feature

把上面這些 harness 元件全部組合起來後，repository 最近跨過了一個門檻: 給 Codex 一句話的 prompt，它可以自己

  1. 驗證 repo 當前狀態
  2. 重現報告中的 bug
  3. 錄一段影片證明 bug 存在
  4. 實作修復
  5. 開 app 自己驗證修復生效
  6. 錄第二段影片證明問題解決
  7. 開 PR
  8. 回應 agent 和人類的 review
  9. 偵測並修 build failure
  10. 只在需要人類判斷時才 escalate
  11. 自己 merge

文章誠實地補了一句: 這種程度的自主性高度依賴這個 repo 的特定結構和工具，沒做類似投資的 repo 不能假設能複製。

整篇最值得記住的: 紀律從 code 移到了 scaffolding

文章最後一段把整個哲學收得很漂亮:

寫軟體仍然需要紀律，但紀律展現的地方從 code 本身移到了 scaffolding。維持 codebase 連貫的工具、抽象、回饋迴路，重要性越來越高。我們最困難的挑戰，現在集中在設計環境、回饋迴路、和控制系統，讓 agent 能完成我們的目標: 大規模建構並維護複雜可靠的軟體。

(Building software still demands discipline, but the discipline shows up more in the scaffolding rather than the code.)

回頭看 harness engineering 這個詞用得蠻精準的: 它不是「prompt 工程」、不是「agent 調教」，而是整套讓 agent 能拉得動車的裝備工程。這篇文章列出的每一條技術 ── worktree 隔離、observability stack、AGENTS.md 當目錄、layered architecture、custom linter、agent-to-agent review、golden principles、doc-gardening agent ── 都是這套裝備的具體零件。

如果你正在打造 coding agent 或 agent-driven 系統，小編覺得這篇有兩個層次的啟發:

  1. 戰術層: 文章裡的每一條都是可以馬上偷的 pattern。worktree、observability、文件結構、layer architecture 這些不需要 OpenAI 等級的資源也能做。
  2. 戰略層: 「agent 做不好不是 prompt 問題，是 harness 不夠好」這個心態，會徹底改變你投資工程資源的方向。

有興趣的請完整讀原文: Harness engineering: leveraging Codex in an agent-first world。