OpenAI 純靠 Agent 寫出百萬行程式碼的秘密：Harness 工程五大原則

最近「Harness」這個詞越來越頻繁地出現。OpenAI 發布的一篇部落格文章終於為這個概念下了清楚的定義。在 Agent 時代，工程師到底該做什麼？讓我們來整理一下。

Harness（線束/工具殼）是讓 AI Agent 能夠影響現實世界的工具外殼。如果推理模型是大腦，那 Harness 就是手腳。讀取檔案、修改程式碼、執行測試、部署上線, , 所有操作都發生在 Harness 內部。

OpenAI 內部團隊從 2025 年 8 月底一個空的儲存庫起步，純靠 Codex Agent 建構了一個百萬行的新產品。條件是：不允許人類手寫程式碼。據報告，耗時僅為手工開發的十分之一。他們在這個過程中歸納出以下五條原則。

Agent 看不到的知識等於不存在

對 Codex 來說，執行期間無法存取的資訊就等於不存在。Google Docs 裡的需求文件、Slack 中達成的架構共識、某個人腦中的隱性知識, , 全都看不見。這和三個月後才加入的新人面臨的處境完全一樣。

因此團隊將所有決策推入儲存庫中的 Markdown 文件、Schema 和執行計畫（ExecPlan）。

• ExecPlan 是在 PLANS.md 中定義的自包含設計文件
• 通過標準：新手讀完後能獨立完成實作
• 存在 Codex 單次 Prompt 連續工作超過 7 小時的案例
• 將 matklad 的 ARCHITECTURE.md 概念擴展到 Agent 場景

不要說「再努力一點」，要問「缺了什麼能力」

早期 Agent 的速度低於預期。原因不在模型能力，而在環境準備不足。每次失敗時，團隊都會問：「缺少了什麼能力？怎樣才能讓 Agent 可讀取、可驗證？」

• 用自研的並行 Helper 取代外部函式庫，與 OpenTelemetry 100% 整合
• 業界常說的「無聊技術」反而對 Agent 更有利（API 穩定性高，訓練資料表示度高）

機械化強制而非文件來保證程式碼一致性

僅靠文件無法維持 Agent 生成程式碼庫的一致性。於是團隊選擇了只機械化強制不變規則、而非鉅細靡遺地指導實作。他們要求在資料邊界必須做解析，但把函式庫的選擇權留給了 Agent。架構固定為分層領域結構，依賴方向由 Linter 驗證。

• 每個業務領域固定層級：Providers → Service → Runtime → UI
• Types、Config、Repo 作為底層共享的橫切關注點
• 自訂 Linter 和結構測試在違規時立即中斷建置
• Linter 本身也由 Codex 撰寫

給 Agent 裝上眼睛，它能獨自工作 6 小時

團隊將 Chrome DevTools Protocol 接入 Agent 執行時期，為 Codex 提供 DOM 快照、截圖和導覽能力。結構是：對比任務前後的快照、觀察執行時期事件，然後在迴圈中不斷修復直到一切正常。

可觀測性工具也以相同方式接入。每個 git worktree 會啟動一個臨時觀測堆疊，工作結束後自動銷毀。

• 透過 Victoria Logs（LogQL）和 Victoria Metrics（PromQL），Agent 可直接查詢日誌和指標
• 「讓服務啟動時間控制在 800ms 以內」這樣的 Prompt 變得可執行
• 單次 Codex 執行專注於一個任務超過 6 小時的情況被定期觀測到

給地圖，別給千頁手冊

上下文管理決定了 Agent 的效能。一開始團隊嘗試把所有內容塞進一個巨大的 AGENTS.md，結果失敗了。matklad 在 2021 年寫的 ARCHITECTURE.md 概念在這裡大放異彩。原則是：簡短俯瞰專案整體結構，只收錄不常變化的內容。對 Agent 同樣適用。

• ARCHITECTURE.md 是程式碼地圖，不是程式碼圖集
• 架構不變規則往往以「某樣東西不存在」的形式來表達
• 明確聲明邊界（boundary），就能約束後續所有實作

尚未解答的問題

即便是 Codex 團隊，也有尚未解答的問題。純靠 Agent 建構的系統能否在數年內保持架構一致性，沒有人知道。模型持續進化後，這套體系本身會如何變化，也是未知數。

有一點是明確的：寫好程式碼的時代正在落幕，設計好環境的時代已經開始。