Communitygithub.com

AgentPilotLab/loop-goal-runner

為 Codex、Claude Code 等 AI 代理提供具有狀態記憶、閘門與停止規則的狀態化目標循環技能。

loop-goal-runner 是什麼?

此技能設計用於將開放式的 AI 代理任務轉換為小型、狀態化且目標明確的操作循環。其核心機制基於四個關鍵要素:目標 (Goal)、狀態 (State)、閘門 (Gate) 和停止規則 (Stop Rule),以確保任務執行有條理且可被客觀驗證。它支援 Codex、Claude Code 等主流 AI 代理平台,透過維護一個持久的 STATE.md 文件來記錄每個獨立目標的進度、驗證結果和學到的經驗,從而實現狀態化記憶。技能提供了詳細的工作流程,引導用戶從任務適用性檢查(Fit Check)開始,到創建或定位狀態文件、定義可衡量的目標、執行單次迭代,最後做出繼續、停止或升級處理的決策。此外,它還包含是否使用子代理(Subagents)或工作樹(Worktrees)的考量準則,並強調在目標達成、遇到障礙或需要人工判斷時應適時停止,確保任務執行高效且安全。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add AgentPilotLab/loop-goal-runner

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Loop Goal Runner

使用此技能將開放式的 Codex 任務轉換為一個小型、狀態化的循環。該循環必須具有明確的目標、持久的狀態、客觀的閘門以及停止規則。保持預設路徑的輕量化;僅在任務證明其有額外成本價值時,才添加子代理或工作樹。

核心契約

每次循環執行必須維護以下四個工件或決策:

  1. 目標 (Goal):當前用戶目標及完成標準。
  2. 狀態 (State):一個持久的 STATE.md 文件或一個明確命名的外部狀態系統。
  3. 閘門 (Gate):測試、lint、類型檢查、建置、資料驗證、截圖檢查或其他客觀證明指令。
  4. 停止規則 (Stop Rule):成功、障礙、最大嘗試次數、最大運行時間、預算限制或需要人工審批的邊界。

若無新鮮的驗證證據,請勿聲稱完成。如果沒有客觀的閘門,請將工作保留在建議/手動模式,並說明這不是一個好的循環候選項。

工作流程

1. 執行循環適用性檢查

在建置或繼續一個循環之前,檢查任務是否合適:

  • 至少每週重複一次,或者時間夠長以致於持久狀態很重要。
  • 具有可以拒絕錯誤輸出的客觀閘門。
  • 可在當前環境中執行。
  • 具有硬性停止條件。
  • 無需對架構、身份驗證、支付、生產環境部署或不可逆操作進行無監督的判斷。

如果其中某項失敗,請解釋失敗的條件並使用正常的一次性工作流程,除非用戶明確要求繼續。

2. 定位或創建狀態

預設情況下,將狀態視為目標範圍內的。每個不同的目標都應擁有自己的持久狀態文件,除非用戶明確要求重用現有狀態文件,或者現有文件明顯屬於同一個活動目標。

狀態路徑優先級:

  1. 使用用戶指定的確切狀態文件路徑(如果有的話)。
  2. 如果正在繼續一個現有目標且其先前的狀態路徑已知,則重用該文件。
  3. 如果目標創建或主要修改一個任務儲存庫或工件目錄,則使用該任務根目錄下的 STATE.md。
  4. 否則,在當前工作空間的 .codex/goals/<goal-slug>/STATE.md 下創建一個目標特定的文件。
  5. 僅在工作空間本身就是目標,或用戶明確選擇時,才使用工作空間根目錄的 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. 執行一次循環迭代

使用此迭代形狀:

  1. 讀取狀態和指示。
  2. 選擇下一個最小的有用行動。
  3. 執行該行動。
  4. 執行相關的閘門或解釋為何無法執行。
  5. 檢視差異或輸出。
  6. 更新選定的目標範圍狀態文件。
  7. 決定繼續、停止或升級處理。

保持變更範圍。在排程自動化之前,優先進行一次可靠的手動運行。

5. 決定是否使用子代理

預設使用單一代理。僅在滿足以下至少一項條件時使用子代理:

  • 可以在並行中進行獨立調查。
  • 建立者/檢查者分工可以顯著降低風險。
  • 任務包含幾個不相關的失敗、子系統或文件。
  • 用戶明確要求並行代理或子代理。

使用子代理時,應用以下模式:

  • 建立者/檢查者:一個代理實作或調查,另一個審查規範遵循情況和程式碼品質。
  • 並行派遣:每個獨立問題領域一個代理。
  • 驗證者:一個全新的代理審查證據,而非隱藏的推理。

不要將子代理的意見視為硬性閘門。客觀驗證仍然具有決定性。

6. 決定是否使用工作樹

當多個代理或長期運行的分支可能同時寫入程式碼時,使用工作樹進行程式碼變更。對於唯讀研究、文件分析、小型單一檔案編輯或非儲存庫工作空間,跳過工作樹。

如果需要工作樹,優先使用 Codex 原生的工作樹支援(如果可用)。否則,僅在確認目標儲存庫並確保工作樹目錄不會被意外提交後,才使用 Git 工作樹。

7. 完成與升級處理

在以下情況發生時,清晰報告並停止:

  • 閘門通過且滿足目標標準。
  • 達到最大嘗試次數、運行時間或預算限制。
  • 需要必要的權限、憑證、外部服務或人工判斷。
  • 同一個障礙在連續三個循環輪次中重複出現。
  • 循環需要觸及架構、身份驗證、支付、生產環境部署、秘密或廣泛的權限,而未經明確的人類批准。

最終回應必須包含當前狀態、驗證證據以及下一步推薦行動。

觸發可靠性

技能觸發是基於描述的。為了使此技能在未來目標模式下自動運行,請將 references/agents-snippet.md 中的片段添加到全局或專案的 AGENTS.md 中。

參考資料

  • references/state-template.md:新 STATE.md 文件的範本。
  • references/agents-snippet.md:可選的持久化指示,用於讓 Codex 在用戶啟動或討論目標時自動調用此技能。

相關技能