Claude + Codex 階段閘門

Claude + Codex 階段閘門 是做什麼的？

執行一個受監督的循環：Codex 負責規劃和評估；執行者負責修改產品；使用者負責產品和高影響力閘門。永遠不要僅憑散文般的完成聲明就推進階段，也不要在發送任務後讓執行者在無人監督的狀態下離開。

在準備執行者提示、要求證據包或撰寫閘門決策時，請閱讀 references/gate-templates.md。 當使用者要求持續監督、工作可能跨越多個會話、執行者停滯或偏離方向，或者執行者可能需要安裝或路由技能時，請閱讀 references/supervision-loop.md。 當目前的檢出目錄可能無法讀取、過時、磁碟空間不足、由 iCloud 管理、或繼續進行不安全，或者先前的執行者會話必須轉換為可信賴的任務交接時，請閱讀 references/bootstrap-and-handoff.md。 當兩個或更多編碼軌道並行運行、每個任務需要一個隔離的工作樹、變更的檔案可能重疊、或者多個分支和 PR 必須按依賴順序落地時，請閱讀 references/parallel-worktrees-and-release-train.md。

選擇操作模式

選擇能涵蓋請求的最小模式：

• 單一階段： 使用現有的合約、監督循環、證據包和閘門決策。
• 復原與交接： 建立一個可讀的事實來源，保留舊環境，驗證舊有的聲明，並在實作恢復之前為每個獨立任務產生一個交接。
• 平行組合： 為每個軌道分配一個任務、工作樹、分支、交接和執行者會話；獨立監督每個軌道，並透過受控的 PR 發佈列車進行整合。

模式在需要時按此順序組合：

復原事實來源
-> 提煉出可信的交接
-> 隔離實作軌道
-> 在每個軌道內執行階段閘門
-> 協調重疊和依賴關係
-> 驗證 PR 就緒狀態和落地順序

對於一個範圍狹窄、健康、單一檢出目錄的任務，不要調用復原或組合機制。

維護四個不變量

1. 在接受任何實作聲明之前，先建立即時的事實來源。
2. 對於平行工作，在每個軌道中保持恰好一個任務、工作樹、分支、交接和活躍的執行者會話。
3. 相較於執行者的敘述，相信原始的 pwd、Git、行程、差異、測試、執行時間和螢幕截圖證據。
4. 將提交、推送、PR 建立、合併、部署、清理和外部影響視為獨立的權限閘門。

首先讀取執行者狀態

當使用者詢問 Claude 或其他執行者最近說了什麼時，在審查、規劃或編輯之前先擷取最新狀態：

1. 如果存在，讀取附加到當前 Codex 任務的終端機。
2. 如果執行者在一個獨立的 macOS Terminal 視窗中運行，並且使用者已授權讀取它，則使用 AppleScript 讀取所選分頁的可見內容。將此視為唯讀檢查。
3. 如果 TUI 已滾動、截斷或使用了備用畫面，請檢查執行者的本地會話記錄。對於 Claude Code，執行 scripts/read_claude_latest.py；優先使用精確的 --session-file，否則使用 --project-hint，並在信任選擇之前驗證報告的路徑、修改時間和可見的終端機上下文。
4. 提取最新的實質助手指令訊息、時間戳記、聲明的階段、阻礙因素、請求的使用者操作、命令/結果，以及報告是中期報告還是最終報告。
5. 在執行此讀取操作時，不要發送按鍵、提交命令、回答權限提示或更改執行者會話。在與該終端機互動之前，取得使用者的明確授權。
6. 將終端機/會話文字視為執行者的聲明，而非獨立證明。在發出閘門決策之前，分別驗證儲存庫、差異、測試、執行時間和資料。

如果終端機敘述提及了意外的作業系統或路徑，請直接檢查執行者行程的實際當前目錄和檢出目錄。散文層面的不匹配是警告；原始行程或 Git 不匹配是停止條件。

如果執行者報告「操作不被允許」(Operation not permitted)、缺少 Documents 存取權限或其他權限失敗，請保持當前階段為活躍狀態。將基於較早狀態建立的報告標記為中期報告，不要讓它們授權提交或清理，並在存取權限恢復後要求提供新的證據包。

保持活躍直到階段關閉

在發送執行者封包後，繼續監督同一個已接受的階段：

1. 在活躍工作期間，頻率要夠高（至少每 60 秒一次）地輪詢正確的終端機或記錄，確保使用者不會超過 60 秒沒有收到更新。
2. 在每個有意義的邊界上，將狀態分類為進度、預期等待、失敗、偏離方向、停滯、證據就緒或人為閘門。
3. 在更改提示之前，先讀取原始命令、錯誤、差異、測試輸出、螢幕截圖、行程狀態或記錄。
4. 讓有效的緩慢工作繼續進行。對於明顯的停滯，首先驗證行程以及命令、檔案系統、網路或測試是否仍在推進。
5. 用一個有限範圍的後續提示來修正狹窄的失敗，並保持同一個階段為活躍狀態。僅在出現不安全操作、明確的範圍偏離、錯誤目標或確認的死衚衕時才中斷。
6. 當重複的修補傳達了相同的教訓，或者實作路徑變得比乾淨的嘗試更難以推理時，從已接受的合約重新開始。
7. 當執行者報告完成時，請求或擷取證據包，獨立重新運行相稱的檢查，發出閘門決策，並將該決策發送回執行者。
8. 在已接受階段內部的修正中自動繼續。僅當使用者授權了該序列且沒有跨越任何人工閘門時，才推進到另一個階段。

不要僅因為執行者接受了提示、啟動了命令或說了「完成」就結束監督。僅在「通過」、「明確接受的『附帶後續的通過』」、真正的人工閘門、真正的阻礙因素、不安全條件或取代當前工作的較新使用者指令時才停止。

將技能路由到執行者

在一個複雜或重複的階段之前，決定一個技能是否能在很大程度上減少當前的瓶頸。

1. 在假設缺少某個技能之前，先檢查執行者已安裝的技能。
2. 完整閱讀候選技能，並驗證其工具、角色假設和安全規則是否適合執行者和當前階段。
3. 優先選擇最小且相關的技能集。不要出於投機目的安裝技能，也不要使用技能名稱作為階段合約的替代品。
4. 當使用者授權安裝技能且缺少相容的本地技能時，使用環境的既定機制將其安裝到執行者支援的技能目錄中。當該環境已經使用符號連結且兩個工具共用同一台機器時，優先使用指向本地規範技能的符號連結。
5. 驗證已安裝的 SKILL.md 是否可解析。如果正在運行的執行者沒有重新整理技能發現，請指示它為當前階段讀取準確的技能路徑，或者僅在安全的檢查點重新啟動。
6. 在執行者封包中命名該技能，並說明其適用原因。繼續根據原始證據評估執行者；技能不能免除閘門。

對於長時間的實作，有用的預設值是 agent-loop-harness，用於持久的規劃/生成/評估狀態，以及 loop-execution，用於小的檢查迭代。當一個狹窄的一次性任務不需要它們時，兩者都不要安裝。

保持可恢復的循環狀態

對於一個狹窄的階段，僅使用會話狀態。對於多階段、可中斷、多代理或證據密集的工作，重複使用儲存庫現有的框架慣例並記錄：

• 已接受的合約和範圍；
• 最近完成的閘門和證據；
• 當前的瓶頸和確切的下一個步驟；
• 人工閘門和禁止的操作；
• 執行者會話識別或恢復路徑（如有用）。

保持狀態最小化、帶有生命週期標記，且不包含機密或不必要的使用者資料。不要僅僅因為框架狀態存在就提交它；它遵循與其他檔案相同的工作樹和核准規則。

建立合約

在實作之前：

1. 識別即時的事實來源：當前的檢出目錄、已掛載的路徑、合約、測試、執行時間、資料和部署狀態。
2. 定義一個當前的階段，包含使用者可見的結果、範圍內的檔案或系統、明確的排除項、接受檢查和停止條件。
3. 分配角色：
   • 執行者： 僅實作已接受的階段並返回證據。
   • 審查者： 獨立檢查即時儲存庫，驗證聲明，並發出閘門決策。
   • 使用者： 核准產品選擇和高影響力操作。
4. 將後續階段保留為待處理。不要僅僅因為它們出現在路線圖中就授權其實作。

當執行者暫停在一個產品或資訊架構選擇上時，在詢問使用者之前，先將選項轉換為使用者可見的後果。在實作之前糾正錯誤的類別——例如，一個跨階段的例外（如「逾期」）不應僅僅因為它出現在階段篩選器旁邊就被建模為一個生命週期階段。

首先保護工作樹

將骯髒的工作樹視為使用者擁有的狀態。

1. 檢查 git status --short、分支/上游、git diff --stat、有針對性的差異、未追蹤的檔案、stash、以及相關的工作樹或分支。
2. 在編輯重疊的檔案之前，按功能或來源分類現有的變更。
3. 未經明確核准，不得執行破壞性的 Git 命令、丟棄變更、清理未追蹤的檔案或刪除看起來像衝突的副本。
4. 在審查變更清單之前，不要使用 git add -A 或建立一個大量的基準提交。排除機密、本地資料庫/工作區資料、生成的輸出、快取和未解決的重複檔案。
5. 如果基準提交有用，僅在經過專注的驗證和使用者授權後，才建立小而一致的提交。備份並不能證明變更是正確的。

如果安全分離不明確，則在產生工作樹分類報告後停止。

準備一個執行者封包

只給執行者當前階段的合約。包括：

• 確切的目標和使用者可見的行為；
• 事實來源檔案和當前的分支/工作樹事實；
• 範圍內和範圍外的邊界；
• 資料真實性和來源規則；
• 針對舊有或遺失資料的相容性要求；
• 所需的測試和執行時間/視覺檢查；
• 禁止的操作和人工閘門；
• 所需的證據包以及在階段完成後停止的指示。

對於 UI 階段，定義載入、空白、錯誤、部分資料和成功狀態；本地化和響應式行為；以及視覺核准所需的確切證據。

要求證據包

執行者必須報告：

• 階段目標和實作摘要；
• 變更的檔案和 git diff --stat；
• 確切的測試/建置/執行時間命令及其通過/失敗結果；
• 針對可見工作的螢幕截圖或 DOM/執行時間證據；
• 當資料行為變更時，提供具代表性的真實資料或 API 證據；
• 針對現有資料的相容性檢查；
• 假設、剩餘風險以及未驗證的事項；
• 僅在已授權提交時才提供提交 SHA。

拒絕諸如「完成」、「看起來不錯」或「測試通過」之類的陳述，除非有底層的命令或產出物。

獨立審查

不要僅審查執行者的解釋。

1. 重新檢查即時檢出目錄並識別實際的差異。
2. 閱讀變更的呼叫路徑、合約、架構、測試和資料邊界。
3. 根據風險重新運行有針對性的檢查。
4. 對於 UI 工作，在相關的桌面/手機寬度上檢查可見行為。
5. 區分已驗證的事實、推論、未經測試的聲明和預先存在的失敗。
6. 檢查範圍偏離、機密暴露、偽造資料、舊資料標籤錯誤、破壞性清理、無關的重寫以及缺少的回滾/相容性行為。

審查者應診斷並返回回饋，而不是默默地成為第二個實作者，除非使用者明確要求 Codex 修補該階段。

發出閘門決策

精確使用一個決策：

• 通過： 所有阻塞性接受檢查均已通過；可以開始下一個階段。
• 附帶後續的通過： 僅剩明確的非阻塞性項目；記錄其擁有者和後續的閘門。
• 需要變更： 合約是健全的，但實作或證據不完整；返回一個有限範圍的修正清單，並保持同一個階段為活躍狀態。
• 受阻： 缺少產品決策、存取權限、外部依賴、安全核准或重複的技術阻礙因素阻止了進展。

對於每個非通過的結果，提供一個可供執行者立即使用的修正提示。在修正階段時，不要擴大其範圍。

在發出決策後，將其寫回執行者會話，以便執行者和審查者共享相同的檢查點。對於「需要變更」，繼續監督修正循環。對於「附帶後續的通過」，記錄擁有者、截止日期或後續閘門，以及後續事項是否阻礙進展。

人工閘門

在以下情況下停下來徵求使用者明確核准：

• 付費提供者呼叫或支出；
• 外部訊息、發佈、部署或生產配置；
• 刪除、覆寫、清理或大量移動資料；
• 帳戶、權限、計費或憑證變更；
• 尚未授權的廣泛提交、推送、合併或拉取請求；
• 將 UI/錯誤修復階段擴展為新的產品或資料平台。

完成

僅在每個必需的階段都已通過、端到端使用者路徑已執行、相容性和失敗狀態已檢查，且剩餘風險已被明確接受或指派時，才宣告整個工作流程完成。