Loop Goal Runner
使用此技能將開放式的 Codex 任務轉換為一個小型、狀態化的循環。該循環必須具有明確的目標、持久的狀態、客觀的閘門以及停止規則。保持預設路徑的輕量化;僅在任務證明其有額外成本價值時,才添加子代理或工作樹。
核心契約
每次循環執行必須維護以下四個工件或決策:
- 目標 (Goal):當前用戶目標及完成標準。
- 狀態 (State):一個持久的
STATE.md文件或一個明確命名的外部狀態系統。 - 閘門 (Gate):測試、lint、類型檢查、建置、資料驗證、截圖檢查或其他客觀證明指令。
- 停止規則 (Stop Rule):成功、障礙、最大嘗試次數、最大運行時間、預算限制或需要人工審批的邊界。
若無新鮮的驗證證據,請勿聲稱完成。如果沒有客觀的閘門,請將工作保留在建議/手動模式,並說明這不是一個好的循環候選項。
工作流程
1. 執行循環適用性檢查
在建置或繼續一個循環之前,檢查任務是否合適:
- 至少每週重複一次,或者時間夠長以致於持久狀態很重要。
- 具有可以拒絕錯誤輸出的客觀閘門。
- 可在當前環境中執行。
- 具有硬性停止條件。
- 無需對架構、身份驗證、支付、生產環境部署或不可逆操作進行無監督的判斷。
如果其中某項失敗,請解釋失敗的條件並使用正常的一次性工作流程,除非用戶明確要求繼續。
2. 定位或創建狀態
預設情況下,將狀態視為目標範圍內的。每個不同的目標都應擁有自己的持久狀態文件,除非用戶明確要求重用現有狀態文件,或者現有文件明顯屬於同一個活動目標。
狀態路徑優先級:
- 使用用戶指定的確切狀態文件路徑(如果有的話)。
- 如果正在繼續一個現有目標且其先前的狀態路徑已知,則重用該文件。
- 如果目標創建或主要修改一個任務儲存庫或工件目錄,則使用該任務根目錄下的
STATE.md。 - 否則,在當前工作空間的
.codex/goals/<goal-slug>/STATE.md下創建一個目標特定的文件。 - 僅在工作空間本身就是目標,或用戶明確選擇時,才使用工作空間根目錄的
STATE.md。
在重用任何現有的 STATE.md 之前,請檢查其「目標」和「當前狀態」部分。如果它們描述了不同的目標,請勿覆蓋或重新利用它。而是創建一個新的目標範圍狀態文件,並簡要說明這種分離。
如果選定的狀態文件不存在且允許檔案編輯,則從 references/state-template.md 創建它。如果不允許編輯,則在回應中起草初始狀態,並請用戶放置它。
在每次循環執行開始時:
- 在計劃之前讀取選定的目標範圍狀態文件。
- 讀取最近的
AGENTS.md或等效的項目指示(如果可用)。 - 提取上次運行、當前狀態、未解決的障礙、下一步行動、驗證歷史、學到的經驗以及狀態文件路徑。
在每次循環執行結束時:
- 僅使用實際採取的行動更新選定的目標範圍狀態文件。
- 記錄驗證指令及其結果。
- 記錄下一步行動或停止原因。
- 保留那些應該在壓縮或未來運行中存活的經驗教訓。
- 除非用戶明確要求,否則不要移動、歸檔或重寫無關目標的狀態。
3. 塑造目標
對於 Codex 目標模式,編寫可衡量的目標:
/goal <objective>. Done when: <objective gate passes>. Constraints: update the selected goal-scoped state file each run; stop after <N> failed attempts or when human judgment is needed.
如果目標已經處於活動狀態,請使用當前目標作為事實來源,除非用戶更改它。如果沒有活動目標,請根據用戶請求推斷一個工作目標並簡要說明。
4. 執行一次循環迭代
使用此迭代形狀:
- 讀取狀態和指示。
- 選擇下一個最小的有用行動。
- 執行該行動。
- 執行相關的閘門或解釋為何無法執行。
- 檢視差異或輸出。
- 更新選定的目標範圍狀態文件。
- 決定繼續、停止或升級處理。
保持變更範圍。在排程自動化之前,優先進行一次可靠的手動運行。
5. 決定是否使用子代理
預設使用單一代理。僅在滿足以下至少一項條件時使用子代理:
- 可以在並行中進行獨立調查。
- 建立者/檢查者分工可以顯著降低風險。
- 任務包含幾個不相關的失敗、子系統或文件。
- 用戶明確要求並行代理或子代理。
使用子代理時,應用以下模式:
- 建立者/檢查者:一個代理實作或調查,另一個審查規範遵循情況和程式碼品質。
- 並行派遣:每個獨立問題領域一個代理。
- 驗證者:一個全新的代理審查證據,而非隱藏的推理。
不要將子代理的意見視為硬性閘門。客觀驗證仍然具有決定性。
6. 決定是否使用工作樹
當多個代理或長期運行的分支可能同時寫入程式碼時,使用工作樹進行程式碼變更。對於唯讀研究、文件分析、小型單一檔案編輯或非儲存庫工作空間,跳過工作樹。
如果需要工作樹,優先使用 Codex 原生的工作樹支援(如果可用)。否則,僅在確認目標儲存庫並確保工作樹目錄不會被意外提交後,才使用 Git 工作樹。
7. 完成與升級處理
在以下情況發生時,清晰報告並停止:
- 閘門通過且滿足目標標準。
- 達到最大嘗試次數、運行時間或預算限制。
- 需要必要的權限、憑證、外部服務或人工判斷。
- 同一個障礙在連續三個循環輪次中重複出現。
- 循環需要觸及架構、身份驗證、支付、生產環境部署、秘密或廣泛的權限,而未經明確的人類批准。
最終回應必須包含當前狀態、驗證證據以及下一步推薦行動。
觸發可靠性
技能觸發是基於描述的。為了使此技能在未來目標模式下自動運行,請將 references/agents-snippet.md 中的片段添加到全局或專案的 AGENTS.md 中。
參考資料
references/state-template.md:新STATE.md文件的範本。references/agents-snippet.md:可選的持久化指示,用於讓 Codex 在用戶啟動或討論目標時自動調用此技能。