先講你今天下午就能做的三件事
如果你已經在用 AI coding agent，而且已經寫了一份 AGENTS.md 或 CLAUDE.md 之類的指令檔，這篇文章裡最值錢的三件事都不用花錢：
第一，把那份指令檔從百科全書改成目錄。OpenAI 的版本只有大約 100 行，真正的知識放在結構化的文件目錄裡，指令檔只負責指路。第二，把修正方法直接寫進自訂 linter 的錯誤訊息。agent 撞牆的那一刻，是它最需要指引也最保證會讀到指引的時刻。第三，把清理技術債改成定期執行的背景任務，而不是每週挪一天人工清。
這三件的成本都接近零，而它們是一個三人團隊花五個月換來的。
OpenAI 發表過一份實作報告，記錄他們如何從一個空的 git repository 開始，在五個月內交付一個公司內部每天都有人在用的產品：約一百萬行程式碼、約 1,500 個已合併的 pull request、團隊從三人成長到七人、人類一行程式碼都沒有手寫。核心主張是工程師的工作性質改變了——從寫程式碼，變成設計環境、把要做的事講清楚、建立回饋迴路。
但這份報告混雜了兩種東西：一種是純粹的知識組織與規則編碼實務，任何規模的團隊今天都能照做（但要注意這份報告的證據全部產生在 OpenAI 自家生態，換到別家 agent 方向合理、效果未經驗證）；另一種需要為每個 git 工作樹建立可開機的應用實例與用完即丟的可觀測性堆疊，那是基礎設施團隊的產出。原文並沒有替讀者分開這兩堆，但它自己留了一句免責聲明，明講這套做法「不應假設它能在沒有同等投資的情況下泛化」——這句話幾乎在所有二手轉述裡都被省略了。
另外有兩個數字不適合被引用：「約十分之一的時間」沒有基準線也沒有方法論，且由工具的販售方自行估計；「一百萬行」則是 agent 最容易灌水的那種指標。本文的兩堆分類為筆者的分析框架，非 OpenAI 官方說法；所有引用的事實與原文引文均附出處與查證日期。若下文與此摘要衝突，以此摘要為準。
他們宣稱什麼
2025 年 8 月底，一個空的 git repository 收到第一個 commit。初始的骨架——repository 結構、CI 設定、格式化規則、套件管理器設定、應用框架——是用 Codex CLI 搭配 GPT-5 生成的。連告訴 agent 該怎麼在這個 repo 裡工作的那份 AGENTS.md，本身也是 Codex 寫的。
五個月後的成績單：
| 項目 | 數字 | 性質 |
|---|---|---|
| 程式碼規模 | 約 1,000,000 行 | 含應用邏輯、基礎設施、工具、文件 |
| 已合併 PR | 約 1,500 個 | 可查核的流程數字 |
| 團隊人數 | 3 人 → 7 人 | 吞吐量隨團隊成長而上升 |
| 人均日 PR | 3.5 個 | 平均值 |
| 人類手寫程式碼 | 0 行 | 刻意設下的約束 |
| 宣稱節省的時間 | 約 9/10 | 自行估計，無基準線 |
資料來源：OpenAI〈Harness engineering: leveraging Codex in an agent-first world〉原文，2026-08-21 查證。最後一列的性質標註為本文判斷。
值得注意的是，他們自陳早期進度比預期慢，而原因不是 Codex 不夠強：
早期進度比我們預期的慢，不是因為 Codex 沒有能力，而是因為環境沒有被充分定義。agent 缺少朝著高層次目標推進所需的工具、抽象與內部結構。我們工程團隊的主要工作，變成了讓 agent 能夠做有用的事。
這導出了整篇報告最可以帶走的一句話。當某件事失敗時，他們的修法幾乎從來不是「再試一次」，而是問：缺了什麼能力，以及要怎麼讓這個能力對 agent 既可見、又可強制？
「可見」和「可強制」是兩件不同的事，而下面兩節的分野正好落在這裡：讓知識可見，幾乎不用錢；讓應用程式的執行狀態可見，很貴。
免費的那一半：四件今天就能做的事
這份報告的證據全部產生在 OpenAI 自己的生態裡：Codex 這個 harness、GPT 系列模型、以及 AGENTS.md 這個檔案慣例，三者是同一家公司一起調出來的。他們可以為了配合模型去改 harness，也可以為了配合 harness 去訓練模型。
所以下面四件事，換到 Claude Code、Gemini CLI 或任何別家的 agent 上，方向是合理的，但效果是否同等，沒有公開資料可以佐證——每家的 harness 怎麼組裝上下文、自動幫你注入了什麼、上下文滿了怎麼壓縮，都不一樣。把它們當成值得一試的方向，不要當成已驗證的移植結論。這篇後面出現的「你的指令檔」一律是這個意思。
這是整份報告投報率最高的一條，而且他們把理由講得比結論還好。原文的說法是：給 Codex 一張地圖，不要給它一本一千頁的操作手冊。
四個理由，每一條都可以獨立成立：
一、上下文是稀缺資源。一份巨大的指令檔會排擠掉任務本身、程式碼、以及真正相關的文件——於是 agent 要嘛漏掉關鍵約束，要嘛開始為了錯誤的目標最佳化。
二、太多指引就等於沒有指引。當所有事情都是「重要」，就沒有事情是重要的。agent 最後只會照著手邊看得到的程式碼依樣畫葫蘆，而不是知道自己該往哪裡去。
三、它會立刻腐爛。一本大部頭手冊會變成過期規則的墳場：agent 分不出哪些還是真的，人類停止維護它，而這個檔案會悄悄變成一個誘人的陷阱（原文用的是 attractive nuisance，一個法律術語，指那種會吸引人靠近、然後傷到人的危險物）。
四、它難以驗證。單獨一大塊文件不適合用程式檢查——覆蓋率、有沒有過期、誰在維護、交叉連結對不對，全都查不了，於是走樣是遲早的事。
他們的替代方案是：AGENTS.md 保持在約 100 行，只當作目錄；結構化的 docs/ 目錄是唯一真相來源，裡面有標註了驗證狀態的設計文件、架構分層地圖、以及一份替每個產品領域與架構層打分數的品質文件。計畫本身也被當成正式產出：小改動用輕量的臨時計畫，複雜工作則寫成帶進度與決策紀錄的執行計畫，直接 check in 進 repo。
而且他們不是靠自律，是用程式強制——專用的 linter 與 CI job 驗證知識庫是否即時、交叉連結是否正確，另有一個定期執行的「文件園丁」agent 掃描與實際程式行為不符的過期文件，並自動開出修正 PR。
這條最便宜，也最容易被跳過。原文只有一句話：
因為這些 lint 是我們自己寫的，我們把補救指示直接寫進錯誤訊息，藉此注入 agent 的上下文。
它為什麼有效，值得展開一下。一般的文件是 agent「可能會讀、也可能不會讀」的東西；但當它撞上一個失敗的檢查，那段錯誤訊息一定會進入它的上下文。把知識放在失敗發生的位置，比放在一份需要主動查閱的文件裡可靠得多——而且成本只是改寫幾行字串。
這也是為什麼「用檢查取代提醒」值得當成一條原則：用 prompt 叮嚀一個架構約束，只對這一次任務有效；用 linter 拒絕違規，對每一次任務都有效，不管當下的上下文裡有什麼。
這條的價值在於他們老實承認了失敗版本。Codex 會複製 repo 裡既有的模式——包括那些不太好的模式——於是時間一長必然走樣。一開始他們用人工處理：
我們團隊以前每個星期五（一週的 20%）都在清理「AI slop」。不出所料，這樣做撐不起來。
改法是把他們稱為「黃金原則」的幾條規則直接編碼進 repo——刻意帶有立場、而且可以用程式判定的規則。原文舉了兩個例子：偏好共用的工具套件而非到處手刻小工具，讓那些必須前後一致的規則集中在一個地方；以及不要「YOLO 式」地探測資料結構，而是在邊界做驗證，或改用有型別定義的 SDK，這樣 agent 就不會在猜測出來的資料形狀上繼續往上蓋。
然後用固定頻率的背景 Codex 任務掃描偏離、更新品質評分、開出針對性的重構 PR。他們說大多數這種 PR 一分鐘內就能審完並自動合併。
他們的比喻是垃圾回收：技術債像高利貸，持續小額還款幾乎永遠優於讓它複利滾大之後痛苦地一次清償。人類的品味只需要寫下來一次，之後在每一行程式碼上持續生效。
這條最容易被當成廢話，但它其實是整篇報告裡最有理論意味的一句：
我們偏好那些能被完整內化、能在 repo 內被推理的依賴與抽象。那些常被稱為「無聊」的技術往往更容易被 agent 建模——因為它們的組合性、API 穩定性，以及它們在訓練資料裡出現得夠多。
「這個函式庫在不在模型的訓練資料裡」被當成技術選型的評估項目。這不是玄學：一個 2019 年就存在、被無數教學文章寫過的套件，模型本來就懂的程度遠遠超過一個上個月才發布的套件；後者你得把整份文件塞進上下文，它才知道你在講什麼。
他們甚至走到了「自己重寫比繞過上游行為便宜」這一步。原文舉的例子是併發控制：他們沒有引入 p-limit 這類現成套件，而是自己實作了一個帶併發上限的 map 工具函式——理由是它與自家的 OpenTelemetry 埋點緊密整合、有 100% 測試覆蓋率、且行為完全符合他們的執行環境預期。
這個決策是站得住的。但它同時也解釋了那一百萬行是怎麼來的——後面會再回到這件事。
買不起的那一半：那些需要一整個團隊的東西
報告裡最吸引人的一段，是他們宣稱 repo 最近跨過了一個門檻：給一個 prompt，Codex 就能端到端交付一個功能。完整清單是這樣的——驗證程式碼庫的當前狀態、重現一個回報的 bug、錄一段影片示範失敗、實作修正、驅動應用程式驗證修正、再錄一段影片示範已解決、開 PR、回應 agent 與人類的意見、偵測並修復 build 失敗、只在需要人類判斷時才交上來、合併。
這段很容易被讀成「提示詞下得好就能這樣」。實際上底下墊了三層基礎設施。
他們讓應用程式可以「按 git worktree 開機」，於是 Codex 能為每一個改動各自啟動並操作一份獨立實例。這意味著應用的啟動流程、設定、連接埠配置、資料庫與外部依賴，全都要能夠被平行地、隔離地拉起來又拆掉。
日誌、指標與追蹤透過一套本機可觀測性堆疊開放給 Codex 查詢，而且是每個工作樹各有一份、用完就拆的——Codex 在一份完全隔離的應用版本上工作，連同它的日誌與指標，任務結束後一起拆除。agent 可以用 LogQL 查日誌、用 PromQL 查指標。
這一層買到的東西很具體：像「確保服務啟動在 800 毫秒內完成」或「這四條關鍵使用者操作流程中，沒有任何 span 超過兩秒」這樣的 prompt，會從空話變成可執行的指令。
他們把 Chrome DevTools Protocol 接進 agent runtime，並建立了操作 DOM 快照、截圖與頁面跳轉的 skill。這讓 Codex 能重現 bug、驗證修正、並對 UI 行為進行推理——上面那份「錄兩段影片」的清單就是靠這一層。
對這一整堆，OpenAI 自己留了一句話。這句話在幾乎所有二手轉述裡都被省略了，但它其實是整篇報告最誠實的一段：
「這個行為高度依賴這個 repository 的特定結構與工具，不應假設它能在沒有同等投資的情況下泛化——至少目前還不行。」
換句話說：那份端到端清單不是 Codex 的能力規格，而是「Codex ＋ 這一套他們花五個月蓋出來的環境」的能力規格。把清單當成前者來讀，會得出錯誤的採購決定。
還有一條更危險的：他們的合併策略
報告裡有一段講吞吐量如何改變合併哲學：repository 幾乎不設會擋住合併的關卡，PR 生命週期很短，測試不穩定（flake）通常用重跑後續處理，而不是無限期地擋住進度。理由是在 agent 吞吐量遠超人類注意力的系統裡，修正很便宜，等待很昂貴。
這條看起來很吸引人，但原文自己接了一句：「這在低吞吐量的環境裡會是不負責任的。在這裡，它通常是正確的取捨。」
對一個每天出一兩個 PR 的專案來說，照抄這條的結果不是速度，是把品質關卡拆掉之後沒有任何東西接住。這是全篇最不該被剪下來單獨引用的一段。
兩個不該被引用的數字
「約十分之一的時間」
原文的說法是他們估計這件事花的時間大約是手寫程式碼的十分之一。這句話沒有基準線（沒有人真的手寫過同一個產品）、沒有對照組、沒有方法論說明，而且由該工具的販售方自行估計。
它作為團隊的主觀感受是有意義的；作為引用來源不是。把「AI 讓開發快十倍」掛上 OpenAI 的名字流傳，這句話會取得一個它本身不具備的權威。
「一百萬行程式碼」
這個數字是真的，但它作為成就的方向可疑，理由前面已經埋好了：他們在選型那一節說明了為什麼寧可自己重寫一個併發控制工具，也不引入現成套件。那個決策本身是合理的，但同樣的決策在一個產品的規模上重複幾百次，一百萬行就是這樣長出來的。
換句話說，「行數多」與「做得多」在這個脈絡裡不是同一件事，而行數恰好是 agent 最容易灌水的那一種指標。原文自己其實也沒有把行數當作論點——他們強調的是流程與紀律。被放大成標題的是別人。
約 1,500 個已合併 PR、三人成長到七人、人均日 3.5 個 PR、專案期間約五個月——這些是流程數字，彼此可互相驗算，也不依賴任何主觀基準。要引用這份報告，引用這些。
「指令檔要短」不只是經驗談，有量測支撐
整份報告裡最可以直接照做的第一條——指令檔當目錄不當百科——OpenAI 給的是經驗。但這件事有獨立的量測依據，而且量出來的曲線比經驗更有說服力。
2025 年 7 月的 IFScale 研究直接測了「規則數量 vs 遵循度」：給模型一份商業報告寫作任務，同時附上 10 到 500 條指令，逐級加密度，測了 20 個模型、七家供應商、每個密度跑五次。結果是：
- 最強的前緣模型在 500 條指令下也只剩 68% 遵循率，沒有任何模型撐得住。
- 衰退分成三種形狀：門檻式（推理模型撐到 150 至 200 條才開始掉）、線性、以及指數式（少數模型幾十條就急墜，地板落在 7% 至 15%）。
- 位置有差：模型對後段指令的違反率高於前段，這個偏差在 150 至 200 條附近最嚴重。也就是說「重要的放前面」只在中等密度下有效。
一、IFScale 測的是「關鍵字納入」型指令（文中必須出現某個詞），不是「遇到什麼情況該怎麼做」這種行為規範。把它的結論外推到 agent 指令檔是本文的推論，不是該研究的直接結果。二、該研究發表於 2025 年 7 月，受測的是當時世代的模型，今天的版本表現會不同。
它能穩固支撐的只有一件事，但這件事就夠用了：遵循度隨規則數量下降，而且模型等級越低掉得越快、越早。這個趨勢在 20 個模型上一致成立。
把兩邊接起來就完整了：OpenAI 說「一份巨大的指令檔會排擠掉任務本身」是從實務端觀察到的症狀；IFScale 給的是同一件事在受控條件下的曲線。你的指令檔不是寫給一個記憶力無限的讀者看的，它跟任務、程式碼、文件在搶同一塊空間，而且規則越多，每一條的效力越低。
如果只做一件事，做哪一件
從最便宜的開始，而且順序有意義。
第一步：量一下你的指令檔有多長。不是憑印象，是實際數行數。如果它超過 OpenAI 那份的兩三倍，先不要急著刪——先做分類。把每一段標成三類其中之一：這是行為規則（agent 該怎麼做決定）、這是目錄資訊（哪裡有什麼）、還是這是狀態快照（目前有哪些服務、哪些套件、哪些版本）。
第二步：狀態快照類的內容，改成指向真正的真相來源。這類段落有一個共同特徵——它描述的東西在別處有更新、更權威的版本（設定檔、指令輸出、註冊表、另一份文件），而指令檔裡的是手抄的副本。手抄副本必然會過期，而且過期時不會有任何警告。這正是原文說的「立刻腐爛」。
第三步：檢查每一條規則指向的東西是否還存在。檔案路徑、工具名稱、指令、子系統——挑幾條實際去驗一次。指令檔的特性是它從來不會執行失敗，所以一條指向不存在事物的規則可以在裡面躺很久，而且因為它讀起來很有說服力，反而會被信任。這是原文那個「誘人的陷阱」講的狀況。
第四步：把留下來的行為規則排序，重要的放前面。依據見上一節。
做完這四步，你會得到一份短很多的檔案。它的價值不在於短，而在於裡面剩下的每一條你都剛剛驗過一次。
至於 linter 錯誤訊息那條，什麼時候做都可以，因為它不需要先整理任何東西——下次你寫或改一條檢查規則時，順手把「該怎麼修」寫進錯誤訊息就是了。
常見問題
Harness（鷹架、外殼）指的是包在 AI agent 外面的整套執行環境：它能呼叫哪些工具、看得到哪些資訊、受到哪些約束、以及出錯時如何得到回饋。Harness engineering 就是刻意設計這一層的工程實務。它與 prompt engineering 的差別在於作用範圍——prompt 管的是單次訊息的品質，harness 管的是 agent 連續自主執行數小時期間的整個運作世界。OpenAI 在這篇實作報告裡的核心主張是：當 agent 表現不好時，問題通常不在模型能力，而在環境沒有被充分定義，所以工程師的工作從寫程式碼轉為設計環境、把要做的事講清楚、建立回饋迴路。查證 2026-08-21｜openai.com/index/harness-engineering
重點不是行數而是形狀：它應該是一張地圖，不是一本百科全書。OpenAI 的做法是讓約 100 行的 AGENTS.md 只負責指路，真正的知識放在結構化的 docs/ 目錄裡當作唯一真相來源，並用專用 linter 與 CI job 自動檢查它有沒有過期、交叉連結對不對。他們給出的四個理由是：巨大的指令檔會排擠掉任務本身與相關程式碼；當所有事都標為重要就等於沒有重點；單一大檔會立刻腐爛成過期規則的墳場；以及一整塊大文件沒辦法用程式檢查。但要注意這份報告的證據全部產生在 OpenAI 自己的生態裡——Codex 這個 harness、GPT 系列模型、以及 AGENTS.md 這個檔案慣例，三者是同一家公司一起調出來的。換到 Claude Code 的 CLAUDE.md、Gemini CLI 或其他 agent，「地圖而非百科」這個方向合理且有獨立研究支持指令密度會拖累遵循度，但效果是否同等，沒有任何公開資料可以佐證，因為每家的 harness 怎麼組裝上下文、自動注入了哪些東西、如何做壓縮，都不一樣。把它當成值得一試的方向，不要當成已驗證的移植結論。查證 2026-08-21｜openai.com/index/harness-engineering
一部分可以，一部分不行，而且 OpenAI 自己在原文裡就寫了免責聲明：這個行為高度依賴該 repo 的特定結構與工具，不應假設它能在沒有同等投資的情況下泛化。可以直接照做的是純知識組織與規則編碼類的實務，成本接近零：把指令檔改成目錄形式、把修正指示寫進自訂 linter 的錯誤訊息、把清理技術債改成定期執行的背景任務。做不到的是需要基礎設施投入的部分：讓應用程式能在每個 git worktree 各開一份實例、為每個 worktree 建立用完即丟的可觀測性堆疊、把 Chrome DevTools Protocol 接進 agent 執行環境。另外他們那套「最少 merge 關卡、測試不穩定就重跑而非阻擋」的策略是高吞吐量下的取捨，原文明說在低吞吐量環境這樣做是不負責任的。查證 2026-08-21｜openai.com/index/harness-engineering
應該分開看待。可查證的是規模與流程數字：約一百萬行、約 1,500 個已合併的 pull request、團隊從三人成長到七人、平均每人每天 3.5 個 PR。不可查證的是效率宣稱：原文寫的是他們估計這大約是手寫程式碼所需時間的十分之一，沒有提供基準線、沒有對照組、也沒有方法論，而且由該工具的販售方自行估計，因此不適合被引用為證據。至於程式碼行數本身作為成就也需要保留——agent 產出的程式碼傾向冗長，原文自己就舉例他們選擇重新實作一個併發控制工具函式而非引入現成套件，這類決策在整個專案重複足夠多次，行數自然會膨脹。查證 2026-08-21｜openai.com/index/harness-engineering
因為那是 agent 最需要指引、也最保證會讀到指引的時刻。OpenAI 的原文寫得很直接：因為這些 lint 是他們自己寫的，所以他們把補救指示直接寫進錯誤訊息，藉此注入 agent 的上下文。一般的文件是 agent 可能會讀、也可能不會讀的東西，但當它撞上一個失敗的檢查時，那段錯誤訊息一定會進入它的上下文。把知識放在失敗發生的位置，比放在一份需要主動查閱的文件裡更可靠，而且成本只是改寫幾行錯誤訊息字串。查證 2026-08-21｜openai.com/index/harness-engineering
這篇實作報告不是新聞。它最早出現在 Hacker News 是 2026 年 2 月 12 日，真正被廣泛討論則是 2026 年 6 月 5 日那次重新提交。文中描述的專案期間是 2025 年 8 月底到大約 2026 年 1 月，與內文所稱的五個月相符。至於 Codex：harness 本身是開源的，openai/codex 採用 Apache 2.0 授權，2025 年 4 月 13 日建立，截至 2026 年 8 月 21 日有 109,089 個 star，任何人都可以下載、檢視與修改；但實際執行推理需要向模型供應商付費或持有訂閱，開源的是外殼不是模型。查證 2026-08-21｜Hacker News Algolia API、GitHub API
結論
這份報告最有價值的部分不是那一百萬行，而是那份「為了讓 agent 能工作，我們被迫先蓋了什麼」的清單。清單本身是誠實的——他們甚至承認早期進度比預期慢、承認每週要花 20% 的時間清 AI 產生的垃圾、承認這套做法不保證能泛化。
但清單裡的項目價格差了好幾個數量級，而原文並沒有替讀者標價。把指令檔改成目錄、把修法寫進 linter 錯誤訊息、把清理排程化，這些是重新組織你已經擁有的東西，今天下午就能做完第一件。為每個工作樹拉起一套用完即丟的可觀測性堆疊，是另一種東西——它不是「更努力地做同一件事」，它是一個基礎設施團隊的季度目標。
兩者混在同一篇文章裡讀，很容易產生一種錯覺：只要態度對了，那份端到端清單就會出現。實際上那份清單是環境的規格，不是模型的規格。
而如果只能帶走一句話，帶走這句：當 agent 卡住的時候，不要問它為什麼這麼笨，問缺了什麼能力，以及要怎麼讓那個能力對它既可見又可強制。這句話不用花錢，而它是那五個月裡真正被證明有效的部分。
本文中「免費／需自建」的兩堆分類為筆者的分析框架，非 OpenAI 官方說法。所有引用的事實、數據與原文引文均附出處與查證日期，可自行複驗；原文為英文，文中引文為本文翻譯。
主要來源：OpenAI〈Harness engineering: leveraging Codex in an agent-first world〉全文、Hacker News Algolia API（發表時間佐證）、GitHub API（openai/codex repository 事實）、arXiv 2507.11538（IFScale）。