saga

Saga

Saga 是一種自主的、規格驅動的開發工作流程，適用於中大型功能，這些功能應在幾乎無人為干預的情況下實作，除了少數幾個離散的接觸點。你扮演編排器：將粗略的提示轉化為嚴謹的規格，然後將實作委派給一群工作者子代理，同時保持自己的上下文視窗乾淨。

整個方法建立在一個賭注上：如果規格定義的每個任務都附有足夠嚴謹的驗證標準以形成一份合約，那麼工作者就可以平行執行並自我驗證，而 saga 幾乎不需要人為監控就能成功。因此，saga 的品質在 Phase 1 就決定了，在寫下任何一行程式碼之前。

核心原則

• 嚴謹的合約勝過良好的意圖。 只有當任務的驗證標準明確到滿足它們時，幾乎不可能做錯，該任務才算準備好委派。模糊是敵人；在規劃期間解決它，而不是在實作期間。
• 不留空白。 在規劃期間，讓每個需求都明確。除非使用者明確授予裁量權，否則不要將決策留給工作者的判斷。工作者永遠不應該猜測「完成」的定義。
• 保護編排器的上下文。 你是長期的協調者。將繁重的閱讀、研究和實作推給工作者；接收精簡的報告回來。將狀態保存在磁碟上（在 saga 目錄的規格樹和 PROGRESS.md 中），這樣你的理解就能在壓縮後存活，並且你可以重新讀取而非重新持有。這能最大化壓縮前的時間，並讓你在整個執行過程中保持連貫。
• 驗證是一等公民。 每個任務以及整個 saga 都帶有預先定義的驗證標準，以及檢查它們的具體方法（電腦使用、互動式 CLI 或測試）。請參閱 references/validation-strategies.md。
• 少數人為接觸點，而非零。 人為核准規格（Phase 1 結束），僅在規格確實無法解決阻礙時才諮詢人為（Phase 2），並由人為進行最終的手動驗收（Phase 3）。

Saga 目錄

每個 saga 都位於自己的目錄中，在儲存庫之外，位於 ~/.sagas/ 下，這樣它就能在編排器會話之間存活，並且可以被新的代理恢復。使用功能名稱的 slug 加上時間戳來唯一命名，例如 ~/.sagas/dark-mode-20260609-0028/。與使用者確認確切路徑並記錄下來——這是 saga 的穩定識別碼。

該目錄包含一個規格檔案的樹狀結構加上一個進度日誌。每個層級都帶有自己的驗證標準，因此細節會隨著 saga 的大小而擴展，而不是讓一個檔案變得臃腫：

~/.sagas/<saga-name>/
├── SAGA.md                      # 概述、環境、saga 層級的退出標準、里程碑索引
├── PROGRESS.md                  # 即時、持續更新的執行日誌和當前狀態
└── milestones/
    ├── 01-<slug>/
    │   ├── MILESTONE.md          # 里程碑規格 + 里程碑層級的驗證標準
    │   └── tasks/
    │       ├── 01-<slug>.md      # 任務規格 + 任務層級的驗證標準
    │       └── 02-<slug>.md
    └── 02-<slug>/
        ├── MILESTONE.md
        └── tasks/ ...

SAGA.md 保持簡短——它索引里程碑並僅包含 saga 範圍的內容。里程碑和任務規格則包含細節。這就是保持上下文乾淨的方法：只讀取你目前正在協調的里程碑或任務的規格，並依賴 PROGRESS.md 來獲取狀態，而不是重新推導。

逐字使用 references/saga-spec-template.md 中的模板和欄位定義。在起草規格之前先閱讀它。

---

Phase 1 — 規劃與規格生成（編排器 + 使用者）

目標：產出一份全面、無歧義的 saga 規格樹。此階段與使用者完全協作。只有當使用者核准規格時才結束。

在此階段向使用者提問時，始終使用 ask_user_question 工具並提供具體選項（單選或多選），而不是開放式問題。當有合理的預設值時，設定 recommended_option_index。開放式的散文問題會拖慢使用者並引發模糊的回答；選項則強制做出明確的決定。

1. 接收與框架化

將請求重新表述為一段問題陳述和功能的大致形狀。識別你需要解決的主要未知數。在 ~/.sagas/ 下選擇一個唯一的 saga 目錄路徑（功能 slug + 時間戳），與使用者確認並建立它；以下所有內容都寫在那裡。

2. 建立機器與執行環境能力

如果不知道這台機器上實際可以測試什麼以及針對這個程式，你無法定義現實的驗證標準。透過先檢查儲存庫和環境，並僅就你無法發現的部分詢問使用者來確定：

• 這是什麼類型的程式？ 網頁應用程式、原生 GUI、TUI、CLI/函式庫、後端服務等。這決定了驗證方法（請參閱 references/validation-strategies.md）。
• 電腦使用是否可用？ 檢查你或雲端工作者是否可以使用電腦使用/瀏覽器自動化功能。如果需要 GUI/網頁驗證但電腦使用僅能遠端使用，請規劃將該驗證透過遠端工作者進行。
• 測試/建置工具鏈是什麼？ 找出測試執行器、建置、lint 和型別檢查指令（例如從 README、CI 設定、套件清單、專案規則中）。確認它們可以執行。
• 如何執行/啟動程式以進行手動或互動式驗證？

將這些發現記錄在 SAGA.md 的環境部分——工作者和任何未來的編排器都依賴它們。

3. 消除每個模糊的間隙

透過 ask_user_question 搭配選項與使用者反覆溝通，直到需求中沒有空白：行為、範圍邊界、邊緣案例、資料形狀、錯誤處理、非目標和驗收標準。將相關問題分批（每次最多 4 個）。僅在剩餘的決策要麼已解決，要麼由使用者明確委派給你裁量時才停止。

4. 定義 saga 退出標準

在分解之前，先撰寫 saga 層級的退出標準：具體、可檢查的條件，表示整個功能已完成且正確。這些是整個 saga 的合約，也是 Phase 3 的基礎。

5. 分解為里程碑與任務

將工作分解為里程碑（連貫、獨立有意義的區塊，按依賴關係排序），並在每個里程碑內分解為任務，其範圍應使單一工作者代理能夠在一次專注的努力中完成一個任務。對於每個任務，指定：範圍、擁有的檔案/表面、對其他任務的依賴，以及驗證標準 + 驗證方法。根據功能真實的依賴關係來務實地塑造拓撲——最大化里程碑內可以平行執行的任務，並在後續工作依賴前期工作的地方排序里程碑。

將其寫入 saga 目錄中的規格樹：里程碑索引和 saga 退出標準在 SAGA.md 中，每個里程碑的詳細資訊和里程碑層級驗證標準在其 MILESTONE.md 中，每個任務的詳細資訊和驗證標準在其自己的任務規格檔案中。每個任務的驗證標準必須根據 references/validation-strategies.md 嚴謹。如果你無法為某個任務寫出嚴謹的標準，則該任務規格不足——將其拆分或回到使用者那裡。

6. 取得核准

呈現 saga 規格——引導使用者瀏覽 SAGA.md 以及里程碑/任務規格——並要求他們核准或要求修改（透過 ask_user_question）。在使用者核准之前，不要開始 Phase 2。 這是主要的人為檢查點。

---

Phase 2 — 實作與驗證（工作者群組，循環）

目標：逐個里程碑執行每個任務以滿足其驗證標準，委派給工作者並保持自己精簡。使用者僅在規格無法解決阻礙時才參與。

編排機制

• 委派，而非實作。 使用 run_agents 啟動工作者。你進行協調；你自己不撰寫功能程式碼。這能保護你的上下文。

• 按平行度批次處理。 在一個里程碑內，將所有獨立任務作為一個 run_agents 批次啟動（共享的 base_prompt，每個任務的 prompt）。按順序執行有依賴的里程碑。使用任務依賴關係的 Mermaid/DAG 心智模型。

• 隔離本地工作者。 當工作者修改同一個儲存庫時，為每個工作者提供自己的 git worktree 和分支。遵循 saga 分支命名慣例，使每個分支都可以追溯到其 saga 目錄、里程碑和任務，而無需查閱 PROGRESS.md：

  saga/<saga-name>/m<M>t<T>-<task-slug>
  

  範例：saga/dark-mode-20260609-0028/m1t2-setup-tokens。使用以下指令建立：

  git worktree add ../saga-<saga-name>-m<M>t<T> -b saga/<saga-name>/m<M>t<T>-<task-slug> <base>
  

  如果你的團隊或儲存庫有分支前綴慣例（例如每個使用者的前綴如 <username>/，或 CI 強制要求的必要前綴），請一致地加上前綴，同時保持 saga/<saga-name>/... 結構不變，以便分支保持可過濾。工作者絕不能共用一個 checkout 或在使用者的當前分支上工作。預先決定合併策略（通常：在里程碑邊界整合每個里程碑的分支）。工作者的變更必須在移除任何 worktree 之前提交、推送或以其他方式持久地交接。

  列出 saga 的所有分支：git branch --list '*saga/<saga-name>/*'

• 用於電腦使用的遠端工作者。 如果某個任務的驗證需要電腦使用，且僅能遠端使用，則在啟用電腦使用的情況下遠端啟動該工作者（或其驗證步驟），並讓它返回一個持久的工件（推送的分支、草稿 PR 或精簡的修補程式/差異），而不是僅將工作留在遠端環境中。

提供給每個工作者的任務合約

將共享規則放入 base_prompt（儲存庫路徑、基礎分支、工具鏈指令、編碼標準、驗證方法、如何回報），並將特定任務放入每個工作者專屬的 prompt。指示每個工作者：

1. 僅實作其分配的任務和擁有的檔案。
2. 在迴圈中自我驗證，根據任務的驗證標準使用規定的方法（電腦使用 / 互動式 CLI 子代理 / 單元 + 整合測試）。迭代修復→驗證，直到所有標準通過或確實受阻。
3. 在清理之前建立持久的交接。 對於本地 git worktree 任務，將驗證過的變更提交到任務分支，並確保分支對編排器可見。對於遠端任務，推送分支、開啟草稿 PR 或返回完整的修補程式/差異；不要將工作的唯一副本留在遠端 checkout 中。如果受阻但有部分有用的工作，在回報之前將其保存為 WIP 提交或修補程式；如果沒有值得保存的部分工作，則明確說明。
4. 僅在持久交接存在後才移除 worktree：git worktree remove <worktree-path> --force。分支或修補程式會保留；worktree 則不會。過時的 worktree 是不可接受的，但清理絕不能丟棄驗證過或有用的部分工作的唯一副本。
5. 精簡回報：分支名稱、提交雜湊或修補程式/推送分支工件、變更的檔案、驗證證據（測試輸出、螢幕截圖、CLI 記錄），以及明確的通過/受阻狀態。保持發現簡潔——你正在保護上下文。

請參閱 references/validation-strategies.md 以選擇和應用驗證方法，以及什麼構成足夠的證據。

編排迴圈

對於每個里程碑，按順序：

1. 啟動里程碑中可平行化的任務作為工作者。立即將每個工作者的可定址代理/執行 ID 記錄在 PROGRESS.md 中，連同其任務、分支和 worktree。顯示名稱不足以用於恢復；新的編排器需要執行 ID 才能與進行中的工作者通訊。
2. 收集回報（讀取工作者的訊息內容；不要僅依賴生命週期成功）。使用每個任務的狀態和證據指標更新 saga 目錄中的 PROGRESS.md。
3. 處理受阻的任務。 如果工作者無法滿足其標準，決定：重新定義範圍並重新委派給同一個工作者（它保留上下文），在其任務規格檔案中調整任務，或者——僅當阻礙是真正的規格缺口或外部決策時——升級給使用者並提供選項。傾向於不升級；規格通常應該有答案。
4. 整合並執行里程碑層級驗證。 將里程碑的分支合併到整合分支，解決衝突，並驗證里程碑整體是否成立（在整合結果上執行相關測試/驗證）。如果有任何工作者不顧指示留下了 worktree，現在移除它（git worktree remove <path> --force），然後繼續。
5. 移動到下一個里程碑。

每當你需要狀態時，從磁碟重新讀取相關的規格檔案和 PROGRESS.md，而不是將其保留在上下文中。隨著進展保持 PROGRESS.md 更新——它是新的編排器用來恢復 saga 的事實來源，因此過時的日誌意味著遺失的 saga。如果你感覺上下文快滿了，先將簡潔的進度檢查點寫入 PROGRESS.md。

---

Phase 3 — 最終驗證（編排器 + 使用者）

目標：確認 saga 的退出標準已滿足，然後交給使用者進行手動驗收。

1. 使用最強可用的方法（GUI/網頁使用電腦使用，TUI 使用互動式 CLI，否則使用完整的測試/整合套件）執行完整的 saga 層級退出標準。針對每個退出標準總結證據。
2. 向使用者呈現一份簡潔的完成報告：建置了什麼、每個退出標準如何驗證、以及他們手動驗證的具體步驟（如何執行/啟動、要檢查什麼）。
3. 透過 ask_user_question 讓使用者進行手動驗收：接受，或回報具體問題。如果他們回報問題，將其捕捉為新任務，執行一個聚焦的 Phase 2 小迴圈（委派 → 自我驗證 → 整合），然後重新呈現。重複直到使用者接受。

僅在使用者確認接受時，才認為 saga 完成。

---

恢復 Saga

由於 saga 目錄和 PROGRESS.md 位於儲存庫之外並捕捉完整狀態，saga 可以在任何時候被新的編排器接手（在壓縮、新會話或交接之後）。當被要求繼續、恢復或接手 saga 時，閱讀 references/continuing-a-saga.md 並遵循它。

實用注意事項

• 除非使用者要求，否則不要提交或開啟 PR；當你這麼做時，請遵循儲存庫的版本控制規則。
• 保持規格樹最新——如果實作迫使範圍或標準發生變化，請更新相關的規格檔案，而不是讓它偏離。
• 對於非常大的 saga（約 10 個以上並行工作者），偏好遠端執行，這樣你就不會耗盡使用者的機器資源。
• 除非被問到，否則不要在面向使用者的摘要中暴露內部工作者代理 ID。

參考檔案

• references/saga-spec-template.md — saga 目錄佈局以及 SAGA.md、MILESTONE.md、任務規格和 PROGRESS.md 的確切模板。在起草規格之前閱讀。
• references/validation-strategies.md — 如何選擇驗證方法、撰寫嚴謹的標準以及收集足夠的證據。在 Phase 1（標準）和 Phase 2（執行）期間閱讀。
• references/continuing-a-saga.md — 新的編排器如何接手現有的 saga 目錄並安全地恢復。當被要求繼續/恢復 saga 時閱讀。