App Server把 Agent 的執行能力開放給客户端。但運行時能夠讀文件、跑測試、管理會話，還不代表一個真實倉庫已經適合長期自主開發。規則只存在於聊天裏、應用很難啓動、日誌需要人手工截圖，都會把開發過程重新卡在人類身上。

這裏的 Harness Engineering，關注的不只是 Agent 外面的一段循環，而是怎樣組織整個軟件工程環境，讓目標可理解、行為可觀察、規則可檢查、反饋可積累。

OpenAI 的《Harness engineering: leveraging Codex in an agent-first world》來自一個主要由 Codex 產出代碼的內部產品實驗。本文提取其中的工程機制，分三部分理解：

• 知識與工具： 倉庫怎樣提供背景，Agent 怎樣觀察真實程序。
• 邊界與驗證： 重要規則怎樣從文字要求變成自動檢查。
• 持續改進： 審查、缺陷和技術債怎樣反饋到後續開發。

一、倉庫怎樣提供 Agent 需要的工程知識h2

從目標與驗收要求出發，把背景、規則和決策放進能夠找到、維護與核對的材料中。

1. Agent-first Engineering：明確人類職責與環境能力h3

Agent-first 不是讓人類退出開發，而是改變投入的位置。模型可以生成實現，但產品目標、取捨、驗收要求與允許的操作範圍，仍然需要人來確定。

例如，“讓筆記頁面更快”並不明確：是首次打開慢、搜索慢，還是輸入延遲？如果要求能夠對應用户路徑、測量入口和目標，Agent 才能判斷應檢查哪一層。

因此，一次開發失敗也可能暴露環境缺口：

• 不知道應該採用什麼設計，可能缺少可發現的架構依據。
• 能修改代碼卻無法驗證，可能缺少可啓動的環境或測試入口。
• 反覆違反同一條規則，可能只有口頭要求，沒有檢查機制。
• 總要人複製日誌，可能缺少可訪問的觀測工具。

這並不排除模型能力不足，而是把問題拆得更具體。工程師可以據此決定，是調整任務、補充知識、增加工具，還是保留人工判斷。

環境建設的產出也不只是給當前任務使用。一條清楚的測試入口、一份準確的模塊説明，可以在後續很多輪開發中重複發揮作用。

2. Repository Legibility：用導航和分層文檔組織知識h3

Repository Legibility 指的是：Agent 能否從倉庫找到理解任務所需的信息，並辨認哪些內容是當前有效的依據。

源碼錶達實現，文檔補充意圖。為什麼模塊不能直接訪問數據庫、某個兼容邏輯為什麼暫時不能刪、設計為何放棄另一種方案，都未必能從函數名字中讀出來。

AGENTS.md 作為導航入口

把全部規範塞進一個巨大文件，會讓當前任務與無關規則爭奪 Context，也增加過時內容的維護難度。更清晰的方式，是用短入口標明：

• 主要目錄和業務模塊在哪裏。
• 架構約束與開發規範去哪裏查。
• 怎樣啓動、測試和檢查項目。
• 當前任務需要遵守哪些關鍵限制。

深入內容留在有主題的文檔中，按任務讀取。一個自擬的簡化組織可以是：

AGENTS.md                  工作入口与索引
docs/
├── architecture.md        模块与依赖边界
├── development.md         启动和验证入口
├── decisions/             重要设计取舍
└── plans/                 活跃计划与已完成记录

重點不是照搬目錄名，而是入口、主題與鏈接關係清楚。文件越多並不等於知識越充分；重複或互相矛盾的説明，反而會降低可用性。

讓文檔與代碼一起維護

文檔需要標明適用範圍，並在實現變化時同步更新。鏈接檢查和結構檢查可以自動完成；行為是否仍與描述一致，則需要結合代碼和測試核對。

倉庫中的知識也不應成為敏感信息堆放區。把必要背景整理為可訪問材料，與把憑證或私人記錄寫進倉庫，是兩回事。

我理解的“可讀”，不只是模型能讀到文本，而是它能沿着清楚的入口，找到當前任務真正需要且足以支持判斷的信息。

3. Execution Plans：保存決策、依賴與工作進度h3

簡單修改可以用短計劃組織；跨模塊任務則需要把目標、步驟、決策和未解決問題留成可接續的材料。

Execution Plan 與長期任務的進度文件有聯繫，但關注範圍更大：

例如，把搜索改成異步請求時，計劃可以解釋為什麼保留舊接口、怎樣避免過期響應覆蓋新結果，以及哪些兼容檢查仍需執行。

這些內容如果只存在於上一輪聊天，新的 Agent 很難發現。進入版本化材料以後，後續修改可以連同當時的約束一起理解，而不是把看起來復雜的邏輯直接簡化掉。

計劃也不能永遠停留在初稿。實現推翻了原有假設，就應記錄新的決策；完成以後保留結果與遺留問題，而不是讓“待辦”一直懸在已經結束的任務上。

二、程序行為與架構規則怎樣被檢查h2

Agent 需要取得真實運行證據，也需要在重要工程邊界上得到明確反饋。

4. Observability：觀察應用、日誌、指標與 Traceh3

Agent 能否自己取得驗證證據，決定了多少工作需要人類代為操作。

可獨立啓動的應用實例

獨立工作區讓代碼變化能夠分開，配套應用實例則讓各自驗證也有清楚對象。否則 A 的代碼在自己的目錄裏，瀏覽器訪問的卻是 B 啓動的服務，結果就難以歸因。

隔離範圍還可能包括測試數據和觀測輸出。是否需要全部隔離，取決於任務，但至少要知道本次證據對應哪份代碼、哪次運行。

不同觀察入口承擔不同職責

例如，“搜索慢”可以先由瀏覽器復現，再用 Trace 找到耗時調用，並從日誌檢查請求與數據範圍。只看模型對源碼的推測，很難確認哪一個解釋成立。

觀測能力不僅是“把日誌塞進 Prompt”。更有效的方式是提供查詢入口、關聯標識和必要摘要，讓 Agent 針對問題取證。大量無關輸出同樣會消耗 Context。

這一層不要求 Agent 永遠自行解決所有問題，而是讓能重複取得的事實，不必每次經過人工搬運。

5. Architecture Invariants：機械驗證重要架構約束h3

文檔説明規則，自動檢查負責穩定執行其中能夠形式化的部分。

以一個假設的分層筆記應用為例，可以規定：UI 不直接訪問持久層，外部輸入在邊界校驗，日誌使用統一結構。這些規則分別可以通過依賴檢查、結構測試和自定義 Linter 驗證。

約束邊界，而不是規定每一行寫法

要求“數據進入領域邏輯前完成校驗”，與要求“每個函數必須用某個固定模板”不同。前者保護系統邊界，後者可能限制了無關的實現選擇。

好的 Invariant 應説明它保護什麼，並能對應明確的違規情形。對模塊依賴的約束，要能識別不允許的引用；對日誌的約束，要能檢查字段和調用方式。

錯誤信息也是反饋接口

“架構檢查失敗”不足以幫助修正。更有用的錯誤應指出違規位置、規則和可行的修復方向，例如：

編輯頁面直接導入了持久層模塊。請通過應用服務訪問筆記，保持界面與存儲邊界。

這不是用更多 Prompt 替代檢查，而是讓檢查失敗後仍有清晰的下一步。

機械規則也有邊界。依賴方向正確，不代表業務邏輯正確；所有 Lint 通過，不代表交互好用。自動檢查應與測試、運行證據和審查互補。

三、開發反饋怎樣進入持續質量治理h2

當前補丁需要修正，重複出現的問題則需要沉澱為後續開發能夠使用的規則和工具。

6. Review Loop：修復當前問題並沉澱反饋h3

一次 PR 的反饋，可以同時產生兩種結果：修復當前補丁，以及降低同類問題再次出現的概率。

例如，審查發現多個頁面重複處理保存狀態。當前修改可以提取共享實現；進一步則需要判斷，是否應補充使用説明或結構檢查，避免後續 Agent 再複製舊模式。

可以把反饋按原因分流：

• 目標理解錯誤： 調整需求和驗收表達。
• 背景缺失： 更新相關文檔與入口。
• 實現缺陷： 修改代碼並補充針對性測試。
• 反覆違反穩定規則： 考慮將要求提升為自動檢查。

不是每條意見都值得變成規則。一次性的局部偏好，寫進全局約束可能影響其他任務；有廣泛價值、能夠清楚檢查的要求，才適合持續執行。

隨着環境成熟，Agent 可以從局部改代碼，擴展到復現問題、實現、驗證、建立 PR 和處理反饋。但這種自主性依賴倉庫工具、驗證與操作授權，不是發出一句“自主完成”就自動擁有全部能力。

尤其是合併、發佈和涉及外部系統的操作，仍應遵守明確的責任和權限邊界。閉環能力與無條件授權不是同一個概念。

7. Garbage Collection：持續清理技術債與重複模式h3

Agent 會參考倉庫已有寫法。壞模式一旦進入共同代碼，就可能成為後續任務的示例：重複工具函數、過時文檔和臨時兼容邏輯都會繼續擴散。

這裏的 Entropy 可以理解為代碼與知識組織逐漸失去一致性；Garbage Collection 則是持續、小範圍地發現和清理這種退化。

例如，可以定期檢查：

• 同一規則是否出現多份不一致實現。
• 文檔描述是否已經落後於代碼。
• 模塊是否繞過了既定邊界。
• 臨時措施是否仍有必要，已知技術債是否得到跟蹤。

清理也必須有證據。兩個函數看起來相似，不代表行為相同；刪除一個“多餘”分支前，需要理解兼容條件並驗證結果。

持續治理的價值，是讓代碼庫提供更好的後續範例，而不只是讓某次 Diff 更整潔。每輪輸出都進入下一輪的工作環境，環境質量會隨這些積累發生變化。

8. Human Attention：分配人工判斷與自動檢查h3

當代碼生成越來越快，人類逐個檢查所有細節容易成為瓶頸。自動測試、規則檢查與針對性審查，可以承擔重複性工作，把人工注意力留給目標、重要取捨和難以形式化的判斷。

原文實驗採用較少的阻塞式合併關卡，強調快速反饋與後續修正。這是特定產品、工具成熟度和風險條件下的取捨，不能直接推廣為“測試失敗也應該先合併”。

如果修改涉及不可逆的數據變更、支付或關鍵權限，修正成本可能很高；如果驗證基礎還不充分，快速合併只會放大未知風險。吞吐變化需要重新設計反饋速度，不代表可以忽略後果。

我從這篇提取的核心是：工程約束不必全部由人反覆提醒，但必須有明確承載它們的位置。 知識進入文檔，穩定規則進入工具，實際行為進入驗證，重要取捨仍由人承擔。

運行時決定 Agent 怎樣執行；工程環境則決定它能否持續找到依據、取得證據，並讓質量隨着開發積累，而不是逐漸退化。

幾個關鍵問題，串起倉庫知識、約束與質量治理h2

Harness Engineering 是重新實現 Agent Loop 嗎？

不是。這裏關注倉庫知識、開發工具、架構規則和反饋機制，解決的是 Agent 在真實項目中怎樣持續開發。

為什麼 AGENTS.md 更適合當導航？

入口應幫助定位當前任務需要的規則，而不是預先加載所有內容。分層文檔更容易按需讀取、維護和核對。

Execution Plan 與任務清單有什麼不同？

清單描述要完成什麼；執行計劃還保存依賴、設計決策、驗證結果和技術債，幫助後續理解為什麼這樣推進。

可觀測性為什麼屬於 Agent 的開發能力？

它讓 Agent 能取得真實程序的證據，而不只是根據源碼猜測。日誌、指標、Trace 和瀏覽器觀察分別補充不同層面的信息。

重要規則為什麼不能只寫在 Prompt 裏？

穩定且可檢查的規則可以由 Lint、結構測試和 CI 持續執行，減少反覆提醒。但無法形式化的判斷仍需要其他反饋。

架構檢查通過，是否代表應用已經正確？

不是。它驗證特定結構約束，不能代替業務測試、用户路徑和實際運行驗證。

為什麼需要持續清理，而不只是修復當前任務？

既有代碼會影響後續生成。壞模式擴散後，修復範圍會擴大；小範圍治理能夠同時改善當前產物和下一輪工作環境。

Agent 能完成 PR 全流程，就可以減少所有人工檢查嗎？

不能。自主程度取決於工具成熟度、驗收能力和操作風險。應明確自動化能可靠承擔的工作，把關鍵判斷保留給相應負責人。

參考資料h2

• OpenAI · Harness engineering: leveraging Codex in an agent-first world