作者 | Ryan Lopopolo

譯者 | 田橙

策劃 | Tina

在過去的五個月里，我們團隊進行了一項挑戰(zhàn)：開發(fā)并發(fā)布一款完全沒有人工編寫代碼的內(nèi)部測試產(chǎn)品。

目前，該產(chǎn)品已經(jīng)擁有內(nèi)部日活用戶和外部 Alpha 測試人員。它在真實的開發(fā)環(huán)境中運行、部署、報錯并接受修復。其獨特之處在于，從應用邏輯到測試腳本，再到 CI 配置、文檔、可觀測性及內(nèi)部工具，每一行代碼都出自 Codex 之手。據(jù)我們估算，這種開發(fā)模式的效率極高，耗時僅為手動開發(fā)代碼的 10%。

人類掌舵，Agent 執(zhí)行。

我們特意設(shè)定了這個限制，就是想看看工程效能能否實現(xiàn)量級上的突破。當時我們需要在短短幾周內(nèi)交付上百萬行代碼，這迫使我們必須重新思考：如果工程師不再把“寫代碼”當成主業(yè)，而是轉(zhuǎn)去設(shè)計環(huán)境、定義意圖并構(gòu)建反饋循環(huán)，好讓 Codex Agent 產(chǎn)出可靠的成果，那么研發(fā)模式到底會發(fā)生什么變化？

在這篇文章中，我們將分享通過 Agent 團隊構(gòu)建全新產(chǎn)品的心得，包括哪些嘗試失敗了，哪些產(chǎn)生了復利效應，以及如何最大化利用我們最寶貴的資源：人類的時間與注意力。

從空倉庫起步

2025 年 8 月底，我們向這個空倉庫提交了第一次 Commit。

初始腳手架由 Codex CLI 調(diào)用 GPT-5 生成，并輔以少量現(xiàn)有模板作為引導，涵蓋了倉庫結(jié)構(gòu)、CI 配置、格式化規(guī)則、包管理器設(shè)置以及應用框架。甚至連指導 Agent 如何在倉庫中工作的初始 AGENTS.md 文件，也是由 Codex 親筆完成。

這里沒有任何預存的人工代碼來作為系統(tǒng)的“錨點”。從一開始，整個倉庫的形態(tài)就是由 Agent 塑造的。

五個月后，該倉庫已擁有約 100 萬行代碼，涵蓋應用邏輯、基礎(chǔ)設(shè)施、工具鏈、文檔和內(nèi)部開發(fā)組件。在此期間，一支僅有 3 名工程師的小團隊驅(qū)動 Codex 開啟并合并了約 1500 個 PR。這意味著平均每位工程師每天產(chǎn)出 3.5 個 PR。令人驚訝的是，隨著團隊擴大到 7 人，人均產(chǎn)出率反而進一步提升。

更重要的是，這并非為了刷量而產(chǎn)出：該產(chǎn)品已被數(shù)百名內(nèi)部用戶使用，其中包括每天重度使用的核心用戶。在整個開發(fā)過程中，人類從未直接貢獻過任何一行代碼。這成了團隊的核心哲學：拒絕人工編寫代碼。

重新定義工程師的角色

由于不再親自動手寫代碼，工程師的工作重心轉(zhuǎn)向了系統(tǒng)設(shè)計、腳手架搭建和杠桿效能。

早期的進展比預期要慢，這并非因為 Codex 能力不足，而是因為環(huán)境的“規(guī)范度”不夠。Agent 缺乏實現(xiàn)高層目標所需的工具、抽象和內(nèi)部結(jié)構(gòu)。于是，工程團隊的首要任務變成了：賦能 Agent 開展有效工作。

在實踐中，這意味著采用深度優(yōu)先的工作方式：將宏大目標拆解為微小的構(gòu)建塊（設(shè)計、代碼、評審、測試等）。驅(qū)動 Agent 構(gòu)建這些塊。利用這些已有的塊去解鎖更復雜的任務。當任務失敗時，修復方案幾乎從不是“再試一次”。因為必須通過 Codex 來推進工作，人類工程師會介入并思考：“缺失了什么能力？我們?nèi)绾巫屵@種能力對 Agent 而言既清晰可見又強制執(zhí)行？”

人類與系統(tǒng)的交互幾乎完全通過 提示詞 完成：工程師描述一項任務，運行 Agent，并授權(quán)其開啟一個 Pull Request。為了推進 PR 最終合入，我們會指示 Codex 在本地審查自己的代碼改動，并請求其他特定的 Agent（無論是在本地還是云端）進行交叉評審。Codex 會根據(jù)人類或 Agent 給出的反饋進行響應，并在循環(huán)中不斷迭代，直到所有 Agent 評審員都感到滿意——這實際上形成了一個所謂的 “拉爾夫·維格姆循環(huán)”（Ralph Wiggum Loop）【見譯注】。Codex 直接調(diào)用我們的標準開發(fā)工具（如 GitHub CLI gh、本地腳本以及集成在倉庫中的技能），自主獲取上下文，無需人類手動在命令行中復制粘貼。

譯注：Ralph Wiggum Loop：這是一個來自《辛普森一家》的梗（那個坐在教室后面自言自語的小男孩），在軟件工程語境下，通常指代一種“自給自足、閉環(huán)且?guī)в心撤N幽默色彩的自推導循環(huán)”。

雖然人類可以審查 PR，但這并非強制要求。隨著時間的推移，我們已將幾乎所有的評審工作都交給了 “Agent 對 Agent” 的協(xié)作模式。

增加應用的“可讀性”

隨著代碼產(chǎn)出率的提升，我們的瓶頸變成了人類的 QA 能力。由于人類的時間和注意力始終是唯一的稀缺資源，我們致力于通過讓應用 UI、日志和指標對 Codex 直接可見且可理解，從而為 Agent 增加更多能力。

例如，我們使應用能夠針對每個 Git 工作樹（worktree）獨立啟動，這樣 Codex 就可以為每一次代碼變更運行并驅(qū)動一個實例。我們還將 Chrome DevTools Protocol 接入 Agent 運行時，并創(chuàng)建了處理 DOM 快照、截圖和導航的技能。這使得 Codex 能夠直接復現(xiàn) Bug、驗證修復結(jié)果并推導 UI 行為。

我們對可觀測性工具也做了同樣的處理。日志、指標和鏈路追蹤通過一個本地的可觀測性棧暴露給 Codex，這個棧對于任何給定的工作樹來說都是臨時的。Codex 運行在該應用的一個完全隔離的版本上，包括其日志和指標，這些內(nèi)容會在任務完成后被銷毀。Agent 可以使用 LogQL 查詢?nèi)罩?，使?PromQL 查詢指標。有了這些上下文，諸如“確保服務啟動在 800ms 內(nèi)完成”或“這四個關(guān)鍵用戶旅程中沒有任何 Trace Span 超過 2 秒”之類的提示詞，就變得具有可操作性了。

我們經(jīng)?？吹絾未?Codex 運行持續(xù)處理一個任務超過 6 小時（通常是在人類睡覺的時候）。

以倉庫知識作為“事實來源”

上下文管理是讓 Agent 處理復雜任務的最大挑戰(zhàn)之一。我們學到的核心教訓是：給 Codex 一張地圖，而不是一本千頁的使用手冊。

我們曾嘗試過“單一 AGENTS.md 大文件”方案，但很快就失敗了：1. 上下文是稀缺資源：巨大的指令文件會擠占任務代碼和相關(guān)文檔的空間。這會導致 Agent 要么遺漏關(guān)鍵約束，要么開始針對錯誤的目標進行優(yōu)化。2. 引導過度等于沒有引導：當所有內(nèi)容都被標榜為“重要”時，就失去了重點。Agent 最終只會進行局部的模式匹配，而無法有目的地理解全局。3. 文檔極易腐化：單體式的手冊很快就會變成陳舊規(guī)則的墳場。Agent 無法判斷哪些規(guī)則依然有效，人類也懶得維護，結(jié)果這份文件反而成了誤導 Agent 的誘餌。4. 難以驗證：這種單一的大塊內(nèi)容無法進行機械化檢查（如覆蓋率、時效性、歸屬權(quán)或交叉鏈接），架構(gòu)偏離也就成了必然。

因此，我們將 AGENTS.md 視為目錄而非百科全書。

代碼庫的知識庫存在于一個結(jié)構(gòu)化的 docs/ 目錄中，并被視為唯一事實來源。一份簡短的 AGENTS.md（約 100 行）被注入到上下文中，它主要充當?shù)貓D的角色，包含指向分布在各處的更深層“事實來源”的指針。

└── SECURITY.md

設(shè)計文檔被編目并索引，其中包含驗證狀態(tài)以及一套定義了“Agent 優(yōu)先”運營原則的核心信條。架構(gòu)文檔提供了一個關(guān)于領(lǐng)域劃分和包分層的頂級地圖。一份質(zhì)量文檔則會對每個產(chǎn)品領(lǐng)域和架構(gòu)層級進行評分，并長期跟蹤其中的差距。

計劃（Plans）被視為一等公民。臨時性的輕量計劃用于微小的變更，而復雜的工作則會被記錄在執(zhí)行計劃中，連同進度和決策日志一起提交到倉庫。活躍計劃、已完成計劃以及已知的技術(shù)債都會進行版本化管理并放在一起，使 Agent 能夠無需依賴外部上下文即可開展工作。

這實現(xiàn)了漸進式披露：Agent 從一個微小、穩(wěn)定的入口點開始，并被告知下一步該去哪里尋找信息，而不是預先就被海量信息所淹沒。

我們通過機械化手段強制執(zhí)行這一點。專門的 Linter 和 CI 任務會驗證知識庫是否處于最新狀態(tài)、是否正確進行了交叉引用以及結(jié)構(gòu)是否合規(guī)。一個循環(huán)運行的“文檔園丁”Agent 會掃描那些無法反映真實代碼行為的陳舊或過時文檔，并開啟修復類 PR。

以“Agent 可讀性”為目標

隨著代碼庫的演進，Codex 的設(shè)計決策框架也隨之進化。

由于整個倉庫完全由 Agent 生成，它首先針對 Codex 的可讀性 進行了優(yōu)化。正如開發(fā)團隊致力于為新入職工程師提高代碼的可導航性一樣，我們?nèi)祟惞こ處煹哪繕耸亲?Agent 能夠直接從倉庫本身推導并理解完整的業(yè)務領(lǐng)域知識。

從 Agent 的視角來看，任何在運行時無法通過上下文獲取的信息，實際上都不存在。存儲在 Google Docs、聊天記錄或存在于人們大腦中的知識，系統(tǒng)是無法訪問的。只有倉庫本地的、版本化的工件（如代碼、Markdown、Schema、可執(zhí)行計劃）才是它可見的全部世界。

我們意識到，隨著時間的推移，我們需要將越來越多的上下文推入倉庫。比如那次讓團隊在架構(gòu)模式上達成一致的 Slack 討論，如果它對 Agent 來說是不可檢索的，那么它就是“不可讀”的——就像對于三個月后入職的新員工來說，這段背景是缺失的一樣。

賦予 Codex 更多上下文，意味著需要組織并暴露正確的信息，以便 Agent 進行推理，而不是用大量的臨時指令讓它不堪重負。就像你會向新隊友介紹產(chǎn)品原則、工程規(guī)范和團隊文化（甚至包括表情符號的使用偏好）一樣，向 Agent 提供這些信息會帶來更加一致的產(chǎn)出。

這種思路讓許多權(quán)衡變得清晰。我們更青睞那些可以被完全內(nèi)化并在倉庫內(nèi)進行推理的依賴項和抽象。那些通常被稱為“乏味”的技術(shù)，往往因為其組合性、API 穩(wěn)定性和在訓練集中的高覆蓋率，更容易被 Agent 建模。在某些情況下，讓 Agent 重新實現(xiàn)一部分功能，比繞過公共庫中不透明的上層行為成本更低。例如，我們沒有引入通用的 p-limit 風格的包，而是實現(xiàn)了自己的并發(fā)映射助手：它與我們的 OpenTelemetry 監(jiān)控緊密集成，擁有 100% 的測試覆蓋率，并且完全符合我們運行時的預期。

將系統(tǒng)的更多部分轉(zhuǎn)化為 Agent 可以直接檢查、驗證和修改的形式，不僅提升了 Codex 的杠桿效能，也同樣造福了其他在同一代碼庫中工作的 Agent（例如 Aardvark）。

強制執(zhí)行架構(gòu)與審美

僅靠文檔不足以保持一個完全由 Agent 生成的代碼庫的連貫性。通過強制執(zhí)行“不變量”而非微觀管理實現(xiàn)細節(jié)，我們讓 Agent 在快速交付的同時，不破壞系統(tǒng)的根基。例如，我們要求 Codex 在系統(tǒng)邊界處必須進行數(shù)據(jù)格式解析，但并不強制規(guī)定實現(xiàn)方式（模型似乎偏好 Zod，但我們從未指定過這個特定的庫）。

Agent 在邊界嚴格且結(jié)構(gòu)可預測的環(huán)境中效率最高。因此，我們圍繞一套僵化的架構(gòu)模型構(gòu)建了應用。每個業(yè)務領(lǐng)域被劃分為一組固定的層級，擁有嚴格驗證的依賴方向和有限的允許連接點。這些約束通過自定義 Linter（當然也是 Codex 生成的?。┖徒Y(jié)構(gòu)化測試進行機械化強制執(zhí)行。

下圖展示了這一規(guī)則：在每個業(yè)務領(lǐng)域（如“應用設(shè)置”）內(nèi)，代碼只能沿著一組固定的層級“向前”依賴（類型定義 → 配置 → 倉庫層 → 服務層 → 運行時 → UI）?？珙I(lǐng)域關(guān)注點（如認證、連接器、遙測、特性開關(guān)）通過單一且明確的接口進入：提供者（Providers）。除此之外的任何依賴都是被禁止的，并由機械化手段強制執(zhí)行。

這種架構(gòu)通常是在擁有數(shù)百名工程師后才會考慮推行的。但在使用編程 Agent 時，它是前置的必要條件：正是這些約束，才使得系統(tǒng)在高速迭代的同時，不會出現(xiàn)腐化或架構(gòu)偏離。

在實踐中，我們通過自定義 Linter、結(jié)構(gòu)化測試以及一小套“審美不變量”來執(zhí)行這些規(guī)則。例如，我們通過靜態(tài)檢查強制要求：結(jié)構(gòu)化日志記錄、架構(gòu)和類型的命名規(guī)范、文件大小限制，以及針對特定平臺的可靠性要求。由于 Linter 是自定義的，我們可以編寫專門的錯誤信息，以便將修復指令直接注入到 Agent 的上下文中。

在以人類為中心的工作流中，這些規(guī)則可能顯得過于死板或受限。但在 Agent 環(huán)境下，它們變成了效能倍增器：規(guī)則一旦被編碼，就會立即應用于所有地方。

與此同時，我們明確區(qū)分了哪些地方需要約束，哪些地方不需要。這非常像領(lǐng)導一個大型工程平臺組織：中央強制執(zhí)行邊界，地方允許自主。 你需要極度關(guān)注邊界、正確性和可復現(xiàn)性；而在這些邊界之內(nèi)，你允許團隊（或 Agent）在表達解決方案時擁有極大的自由。

最終生成的代碼并不總是符合人類的審美偏好，但這沒關(guān)系。只要產(chǎn)出是正確的、可維護的，并且對未來的 Agent 運行而言是可理解的，它就達到了標準。

人類的審美會持續(xù)反饋到系統(tǒng)中。評審評論、重構(gòu) PR 以及面向用戶的 Bug 都會被轉(zhuǎn)化為文檔更新，或直接編碼進工具鏈。當文檔不足以約束行為時，我們就將規(guī)則晉升為代碼。

吞吐量的提升改變了合并哲學

隨著 Codex 吞吐量的增加，許多傳統(tǒng)的工程規(guī)范反而變得適得其反。

倉庫運行時的阻塞性合并門檻極低。Pull Request 的生命周期非常短。對于測試偶發(fā)失敗，通常通過后續(xù)運行來解決，而不是無限期地阻塞進度。在一個 Agent 吞吐量遠超人類注意力的系統(tǒng)中，糾錯是廉價的，而等待是昂貴的。

在低吞吐量的傳統(tǒng)環(huán)境中，這樣做是不負責任的；但在這里，這通常是正確的權(quán)衡。

“Agent 生成”的真正含義

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

Agent 產(chǎn)出的內(nèi)容包括：- 產(chǎn)品代碼與測試腳本 - CI 配置與發(fā)布工具 - 內(nèi)部開發(fā)者工具 - 文檔與設(shè)計歷史 - 評估框架（Evaluation harnesses）- 評審評論及回復 - 管理倉庫本身的腳本 - 生產(chǎn)環(huán)境儀表盤的定義文件

人類依然掌控全局，只是工作的抽象層級變了。我們現(xiàn)在的任務是排列優(yōu)先級、把用戶反饋轉(zhuǎn)化為驗收標準，并最終對結(jié)果進行把關(guān)。一旦 Agent 開發(fā)受阻，這就是一個明確的信號，提醒我們要去復盤：系統(tǒng)里到底缺了什么？是工具不夠，護欄不穩(wěn)，還是文檔有誤？找到癥結(jié)后，我們會把這些反饋注入倉庫，但依然堅持讓 Codex 自己動手來編寫修復方案。

Agent 直接使用我們的標準開發(fā)工具。它們獲取評審反饋、進行行內(nèi)回復、推送更新，并且通常會自主壓縮（Squash）并合并自己的 PR。

持續(xù)提升的自主化水平

隨著越來越多的開發(fā)環(huán)路（測試、驗證、評審、反饋處理及故障恢復）被直接編碼進系統(tǒng)中，該倉庫最近跨越了一個具有里程碑意義的門檻：Codex 已經(jīng)能夠端到端地驅(qū)動新特性的開發(fā)。

僅需一段提示詞，Agent 現(xiàn)在就可以自主完成以下流程：- 驗證代碼庫的當前狀態(tài) - 復現(xiàn)報告的 Bug- 錄制一段展示故障過程的視頻 - 實現(xiàn)修復方案 - 通過操作應用來驗證修復結(jié)果 - 錄制第二段展示修復效果的視頻 - 開啟 Pull Request- 響應 Agent 及人類的反饋 - 檢測并修復構(gòu)建失敗 - 僅在需要人類判斷時才上報 - 合并變更

這種行為極度依賴于本倉庫特定的結(jié)構(gòu)和工具鏈。在沒有類似投入的情況下，不應假設(shè)這種能力可以被直接泛化，至少目前還不行。

熵增與垃圾回收

完全的 Agent 自主權(quán)也帶來了全新的挑戰(zhàn)。Codex 會復制倉庫中已有的模式——即便是那些不均衡或非最優(yōu)的模式。 隨著時間的推移，這不可避免地會導致架構(gòu)偏離。

最初，人類通過手動方式解決這個問題。我們的團隊曾固定在每周五（占一周工作時間的 20%）清理“AI 廢料”。不出所料，這種模式根本無法擴展。

針對這些問題，我們選擇將所謂的“金科玉律”直接寫入代碼倉庫，并建立了一套周期性的清理機制。這些原則是一些帶有明確主張的機械化規(guī)則，目的是確保代碼庫在后續(xù)的 Agent 運行中始終保持清晰、一致。具體實踐包括：第一，我們更傾向于使用共享的工具包，而不是手寫輔助函數(shù)，這樣可以集中管理那些不變量；第二，我們拒絕“全憑運氣”的數(shù)據(jù)探測，必須在邊界處進行校驗，或者依賴強類型 SDK，防止 Agent 采樣猜測的數(shù)據(jù)形狀來編寫代碼。我們會定期運行一組 Codex 后臺任務，專門掃描偏離規(guī)則的代碼，更新質(zhì)量評分并開啟針對性的重構(gòu) PR。由于這些規(guī)則非常明確，大部分 PR 在一分鐘內(nèi)就能完成評審并自動合并。

這種機制運行起來就像“垃圾回收”。技術(shù)債就像高利貸：連續(xù)進行小額償還，幾乎總是優(yōu)于讓其復滾并最終在痛苦的爆發(fā)式清理中解決。人類的審美被捕獲一次后，便會持續(xù)強制執(zhí)行到每一行代碼中。這還讓我們能夠在日常工作中及時發(fā)現(xiàn)并消除不良模式，而不是任由它們在代碼庫中蔓延數(shù)天甚至數(shù)周。

我們?nèi)栽谔剿鞯念I(lǐng)域

到目前為止，這套策略在 OpenAI 內(nèi)部產(chǎn)品的發(fā)布和推廣中表現(xiàn)良好。通過為真實用戶構(gòu)建真實產(chǎn)品，我們的投入得以為現(xiàn)實需求服務，并引導系統(tǒng)走向長期可維護。

目前我們尚不清楚，在一個完全由 Agent 生成的系統(tǒng)中，其架構(gòu)連貫性在長達數(shù)年的跨度下會如何演進。我們?nèi)栽诿魅祟惻袛嗔υ诤翁幠墚a(chǎn)生最大的杠桿效應，以及如何將這種判斷力轉(zhuǎn)化為可沉淀、可產(chǎn)生復利的規(guī)則。同時，隨著模型能力持續(xù)增強，這套系統(tǒng)將如何進化也仍是未知數(shù)。

但有一點已經(jīng)非常明確：構(gòu)建軟件仍然需要嚴謹?shù)募o律，只不過這種紀律不再體現(xiàn)在代碼編寫上，而是體現(xiàn)在“腳手架”的搭建上。那些能保持代碼庫連貫性的工具鏈、抽象層和反饋循環(huán)，正變得愈發(fā)重要。

我們現(xiàn)在面臨的最艱巨挑戰(zhàn)在于如何設(shè)計環(huán)境、反饋循環(huán)和控制系統(tǒng)。唯有如此，才能幫助 Agent 達成我們的目標，即大規(guī)模地構(gòu)建并維護復雜且可靠的軟件。

隨著 Codex 等 Agent 承擔起軟件生命周期中越來越多的份額，這些問題將變得至關(guān)重要。希望這些早期教訓能幫助你思考該在何處投入精力，從而讓你能更純粹地去創(chuàng)造產(chǎn)品。

https://openai.com/index/harness-engineering/