駕馭工程：在代理人優先的世界中發揮 Codex 的力量 | OpenAI

2026 年 2 月 11 日

駕馭工程：在代理人優先的世界中發揮 Codex 的力量

作者：Ryan Lopopolo，技術人員

在過去的五個月裡，我們的團隊一直在進行一項實驗：在不手寫任何一行程式碼的情況下，開發並發佈一款軟體產品的內部測試版。

該產品已有內部的每日使用者和外部的 Alpha 測試者。它能正常發佈、部署、出錯並得到修復。不同之處在於，每一行程式碼——包括應用邏輯、測試、CI 配置、文件、可觀測性和內部工具——都是由 Codex 編寫的。我們估計，開發這個產品所花費的時間大約只有手寫程式碼的 1/10。

人類掌舵，代理人（Agents）執行。

我們刻意選擇了這個限制，以便建立必要的機制來實現工程效率的數量級提升。我們只花了幾週時間就交付了最終達百萬行規模的程式碼。為了做到這一點，我們需要理解當軟體工程團隊的主要工作不再是編寫程式碼，而是設計環境、指定意圖並建立反饋迴路，讓 Codex 代理人能夠可靠地工作時，情況會發生什麼變化。

這篇文章分享了我們與代理人團隊共同開發全新產品的心得——哪些地方出了問題、哪些優勢產生了複利效應，以及如何最大化我們唯一真正稀缺的資源：人類的時間與注意力。

我們從一個空的 git 儲存庫開始

空儲存庫的第一次提交發生在 2025 年 8 月下旬。

最初的腳手架（Scaffold）——包括儲存庫結構、CI 配置、格式化規則、套件管理器設置和應用框架——是由 Codex CLI 使用 GPT-5 並在一組現有模板的引導下生成的。甚至連指導代理人如何在儲存庫中工作的初始 AGENTS.md 文件，本身也是由 Codex 編寫的。

系統中沒有預先存在的人類編寫程式碼來作為錨點。從一開始，儲存庫就是由代理人塑造的。

五個月後，該儲存庫包含了約一百萬行程式碼，涵蓋應用邏輯、基礎設施、工具、文件和內部開發實用程式。在此期間，僅由三名工程師驅動 Codex，就開啟並合併了約 1,500 個拉取請求（PR）。這相當於每位工程師每天平均處理 3.5 個 PR，令人驚訝的是，隨著團隊擴大到現在的七名工程師，產出率反而進一步提升。重要的是，這並非為了產出而產出：該產品已被內部數百名使用者使用，其中包括每日使用的重度使用者。

在整個開發過程中，人類從未直接貢獻過任何程式碼。這成了團隊的核心理念：絕不手寫程式碼。

重新定義工程師的角色

不親自動手編寫程式碼引入了一種不同的工程工作，重點在於系統、腳手架和槓桿作用。

早期的進展比我們預期的要慢，這並非因為 Codex 能力不足，而是因為環境描述不夠具體。代理人缺乏向高階目標推進所需的工具、抽象和內部結構。我們工程團隊的主要工作變成了賦能代理人去執行有用的工作。

在實踐中，這意味著「深度優先」的工作方式：將大目標分解為較小的構建塊（設計、程式碼、審查、測試等），提示代理人構建這些塊，並利用它們來解鎖更複雜的任務。當出現失敗時，修復方法幾乎從不是「再試一次」。因為取得進展的唯一途徑是讓 Codex 完成工作，人類工程師總是會介入任務並詢問：「缺少了什麼能力？我們如何讓這種能力對代理人來說既清晰可見又可強制執行？」

人類幾乎完全透過提示（Prompts）與系統互動：工程師描述任務，運行代理人，並允許其開啟拉取請求。為了推動 PR 完成，我們指示 Codex 在本地審查自己的更改，要求在本地和雲端進行額外的特定代理人審查，回應任何人類或代理人給出的反饋，並在循環中迭代，直到所有代理人審查者都滿意為止（這實際上是一個 Ralph Wiggum 循環⁠）。Codex 直接使用我們的標準開發工具（gh、本地腳本和儲存庫嵌入的技能）來獲取上下文，而不需要人類在 CLI 中進行複製貼上。

人類可以審查拉取請求，但並非必須。隨著時間的推移，我們已將幾乎所有的審查工作推向代理人對代理人的處理方式。

提高應用的可讀性（Legibility）

隨著程式碼產出量的增加，我們的瓶頸變成了人類的 QA 能力。由於固定約束一直是人類的時間和注意力，我們致力於透過讓應用 UI、日誌和應用指標本身對 Codex 直接可讀，來為代理人增加更多能力。

例如，我們讓應用程式可以針對每個 git 工作樹（worktree）啟動，這樣 Codex 就可以為每個更改啟動並驅動一個實例。我們還將 Chrome DevTools 協定接入代理人運行環境，並創建了處理 DOM 快照、螢幕截圖和導航的技能。這使 Codex 能夠直接重現錯誤、驗證修復並推論 UI 行為。

我們對可觀測性工具也做了同樣的處理。日誌、指標和追蹤透過一個本地可觀測性堆疊暴露給 Codex，該堆疊對任何給定的工作樹都是臨時性的。Codex 在一個完全隔離的應用版本上工作——包括其日誌和指標，這些內容在任務完成後會被銷毀。代理人可以使用 LogQL 查詢日誌，使用 PromQL 查詢指標。有了這些上下文，諸如「確保服務啟動在 800 毫秒內完成」或「這四個關鍵使用者路徑中沒有任何跨度超過兩秒」之類的提示就變得可行了。

我們經常看到單個 Codex 運行在單個任務上持續工作超過六個小時（通常是在人類睡覺的時候）。

我們將儲存庫知識作為唯一事實來源

上下文管理是讓代理人在處理大型複雜任務時發揮效用的最大挑戰之一。我們學到的最早教訓之一很簡單：給 Codex 一張地圖，而不是一本 1,000 頁的說明手冊。

我們嘗試過「一個巨大的 AGENTS.md」方法。它以可預見的方式失敗了：

因此，我們不再將 AGENTS.md 視為百科全書，而是將其視為目錄。

儲存庫的知識庫存在於一個結構化的 docs/ 目錄中，被視為唯一事實來源。一個簡短的 AGENTS.md（約 100 行）被注入到上下文中，主要作為地圖，指向其他地方更深層的事實來源。

儲存庫內知識庫佈局。

設計文件被編目和索引，包括驗證狀態和一組定義代理人優先操作原則的核心信念。架構文件提供了領域和套件分層的高階地圖。質量文件對每個產品領域和架構層進行評分，追蹤隨時間變化的差距。

計劃被視為一等公民產物。臨時的輕量級計劃用於小型更改，而複雜的工作則記錄在執行計劃中，並帶有進度和決策日誌，這些日誌會提交到儲存庫中。活動計劃、已完成計劃和已知的技術債務都進行了版本控制並共同存放，使代理人能夠在不依賴外部上下文的情況下運作。

這實現了漸進式揭示：代理人從一個小而穩定的入口點開始，並被告知下一步該看哪裡，而不是預先被海量資訊淹沒。

我們透過機械手段強制執行這一點。專用的 Linter 和 CI 任務會驗證知識庫是否是最新的、是否已交叉連結且結構正確。一個定期的「文件園藝」代理人會掃描陳舊或過時的、無法反映實際程式碼行為的文件，並開啟修復拉取請求。

代理人可讀性是目標

隨著程式碼庫的演進，Codex 的設計決策框架也需要隨之演進。

由於儲存庫完全由代理人生成，它首先針對 Codex 的可讀性進行了優化。就像團隊致力於提高程式碼對新進工程師的導航性一樣，我們人類工程師的目標是讓代理人能夠直接從儲存庫本身推論整個業務領域。

從代理人的角度來看，任何它在運行時無法在上下文中訪問的東西，實際上都不存在。存在於 Google Docs、聊天記錄或人們腦袋裡的知識，系統是無法訪問的。它能看到的只有儲存庫本地的、版本化的產物（例如：程式碼、markdown、schemas、可執行計劃）。

我們意識到，隨著時間的推移，我們需要將越來越多的上下文推入儲存庫。那場讓團隊在架構模式上達成一致的 Slack 討論？如果它對代理人來說是不可發現的，那麼它就是不可讀的，就像對三個月後加入的新人來說是未知的一樣。

給予 Codex 更多上下文意味著組織並暴露正確的資訊，以便代理人可以對其進行推論，而不是用臨時指令淹沒它。就像你會引導新隊友了解產品原則、工程規範和團隊文化（包括表情符號偏好）一樣，給予代理人這些資訊會帶來更一致的產出。

這種框架澄清了許多權衡。我們偏好那些可以在儲存庫內完全內化和推論的依賴項和抽象。通常被描述為「無聊」的技術往往更容易被代理人建模，因為它們具有組合性、API 穩定性以及在訓練集中的代表性。在某些情況下，讓代理人重新實現部分功能，比繞過公共庫中不透明的上游行為成本更低。例如，我們沒有引入通用的 p-limit 風格套件，而是實現了自己的並發映射助手：它與我們的 OpenTelemetry 儀表緊密集成，具有 100% 的測試覆蓋率，且行為完全符合我們運行環境的預期。

將更多系統轉化為代理人可以直接檢查、驗證和修改的形式，不僅增加了 Codex 的槓桿作用，也增加了在該程式碼庫上工作的其他代理人（例如 Aardvark）的槓桿作用。

強制執行架構與品味

單靠文件無法保持完全由代理人生成的程式碼庫的一致性。透過強制執行不變量（Invariants），而不是微觀管理實現，我們讓代理人在不破壞基礎的情況下快速交付。例如，我們要求 Codex 在邊界處解析數據形狀，但不規定如何實現（模型似乎喜歡 Zod，但我們沒有指定必須使用該庫）。

代理人在具有嚴格邊界和可預測結構的環境中最有效，因此我們圍繞僵化的架構模型構建了應用程式。每個業務領域被劃分為一組固定的層，具有嚴格驗證的依賴方向和有限的允許邊緣。這些約束透過自定義 Linter（當然也是 Codex 生成的！）和結構測試進行機械式強制執行。

下圖顯示了規則：在每個業務領域（例如應用設置）內，程式碼只能透過一組固定的層「向前」依賴（Types → Config → Repo → Service → Runtime → UI）。橫切關注點（認證、連接器、遙測、功能旗標）透過單一顯式介面進入：Providers。任何其他行為都是不允許的，並會被機械式強制執行。

這種架構通常是你擁有數百名工程師時才會推遲實施的。對於編碼代理人來說，這是早期先決條件：約束是實現速度且不產生腐敗或架構偏移的關鍵。

在實踐中，我們使用自定義 Linter 和結構測試，加上一組小的「品味不變量」來強制執行這些規則。例如，我們透過自定義 lint 靜態強制執行結構化日誌、Schema 和類型的命名慣例、文件大小限制以及平台特定的可靠性要求。由於 lint 是自定義的，我們會編寫錯誤訊息，將修復指令注入到代理人上下文中。

在以人為本的工作流中，這些規則可能顯得教條或束縛。對於代理人來說，它們變成了乘數：一旦編碼，它們就會立即應用於所有地方。

同時，我們明確區分了哪些地方約束重要，哪些地方不重要。這類似於領導一個大型工程平台組織：集中強制執行邊界，局部允許自主。你深切關注邊界、正確性和可重複性。在這些邊界內，你允許團隊——或代理人——在解決方案的表達方式上有很大的自由。

生成的程式碼並不總是符合人類的風格偏好，這沒關係。只要產出是正確的、可維護的，並且對未來的代理人運行是可讀的，它就達到了標準。

人類的品味會不斷反饋到系統中。審查評論、重構拉取請求和麵向使用者的錯誤會被捕獲為文件更新，或直接編碼到工具中。當文件不足以約束時，我們就將規則提升為程式碼。

產出量改變了合併哲學

隨著 Codex 產出量的增加，許多傳統的工程規範變得適得其反。

儲存庫在最小化阻塞合併門檻的情況下運作。拉取請求的生命週期很短。測試的不穩定性（Flakes）通常透過後續運行來解決，而不是無限期地阻塞進度。在代理人產出量遠超人類注意力的系統中，糾錯是廉價的，而等待是昂貴的。

在低產出環境中，這是不負責任的。但在這裡，這通常是正確的權衡。

「代理人生成」的實際含義

當我們說程式碼庫是由 Codex 代理人生成時，我們指的是程式碼庫中的一切。

代理人生產：

人類始終參與其中，但在與以往不同的抽象層級上工作。我們排列工作優先級，將使用者反饋轉化為驗收標準，並驗證結果。當代理人遇到困難時，我們將其視為一個信號：識別缺失的東西——工具、護欄、文件——並將其反饋回儲存庫，始終透過讓 Codex 本身編寫修復程式來完成。

代理人直接使用我們的標準開發工具。它們提取審查反饋、在線回應、推送更新，並經常自行壓縮（squash）並合併自己的拉取請求。

不斷提高的自主水平

隨著越來越多的開發循環被直接編碼到系統中——測試、驗證、審查、反饋處理和恢復——儲存庫最近跨越了一個有意義的門檻，Codex 現在可以端到端地驅動一個新功能。

給定一個單一提示，代理人現在可以：

這種行為高度依賴於該儲存庫的特定結構和工具，不應假設在沒有類似投入的情況下可以推廣——至少目前還不行。

熵與垃圾回收

完全的代理人自主也引入了新的問題。Codex 會複製儲存庫中已存在的模式——甚至是參差不齊或次優的模式。隨著時間的推移，這不可避免地會導致偏移。

最初，人類手動處理這個問題。我們的團隊過去每週五（一週時間的 20%）都在清理「AI 廢料」。不出所料，這無法規模化。

相反，我們開始將所謂的「黃金原則」直接編碼到儲存庫中，並建立了一個定期的清理流程。這些原則是武斷的、機械的規則，旨在保持程式碼庫對未來代理人運行的可讀性和一致性。例如：(1) 我們偏好共享的實用程式包而不是手寫的助手函數，以保持不變量的集中化；(2) 我們不以「YOLO 風格」探測數據——我們驗證邊界或依賴類型化的 SDK，這樣代理人就不會意外地基於猜測的形狀進行構建。在固定的節奏下，我們有一組後台 Codex 任務掃描偏差、更新質量等級並開啟有針對性的重構拉取請求。其中大多數可以在一分鐘內完成審查並自動合併。

這運作起來就像垃圾回收。技術債務就像高利貸：持續小額償還幾乎總是比讓其複利增長然後在痛苦的爆發中處理要好。人類的品味被捕獲一次，然後在每一行程式碼上持續強制執行。這也讓我們能夠每天捕獲並解決不良模式，而不是讓它們在程式碼庫中蔓延數天或數週。

我們仍在學習什麼

到目前為止，這一策略在 OpenAI 內部的發佈和採用過程中運作良好。為真實使用者開發真實產品有助於將我們的投入錨定在現實中，並引導我們走向長期可維護性。

我們尚不知道在一個完全由代理人生成的系統中，架構的一致性在數年後會如何演變。我們仍在學習人類判斷在哪裡能產生最大的槓桿作用，以及如何編碼這種判斷使其產生複利。我們也不知道隨著模型隨時間變得越來越強大，這個系統將如何演變。

已經明確的是：開發軟體仍然需要紀律，但這種紀律更多地體現在腳手架上，而非程式碼本身。保持程式碼庫一致性的工具、抽象和反饋迴路變得越來越重要。

我們現在最困難的挑戰集中在設計環境、反饋迴路和控制系統，以幫助代理人實現我們的目標：大規模地構建和維護複雜、可靠的軟體。

隨著像 Codex 這樣的代理人承擔起軟體生命週期中更大的部分，這些問題將變得更加重要。我們希望分享這些早期教訓能幫助你思考該在哪裡投入精力，以便你可以專注於創造事物。

作者

致謝

特別感謝對本文做出貢獻的 Victor Zhu 和 Zach Brock，以及開發這款新產品的整個團隊。

延伸閱讀

工程 2026 年 2 月 13 日

工程 2026 年 2 月 4 日

工程 2026 年 1 月 29 日