dispatching-subagents

name	dispatching-subagents
description	Use when about to spawn or delegate work to a subagent (Agent/Task tool), choosing a model tier (haiku/sonnet/opus) for a task, writing a delegation prompt, deciding whether something should be delegated at all, verifying a delegated result, or after a delegated task failed twice and needs escalation.

🌐 English version · 繁體中文（正本 / canonical）

模型調度守則（dispatching-subagents）

目標：主對話 context 只裝結論與決策，執行細節外包。派工 prompt 模板見 references/templates.md。

0. 什麼時候「不要」派工（先看這條，避免過度委派）

• 已知確切檔案與位置的單點查證（例：看某設定檔第 N 行的值）→ 自己 Read，比派 agent 便宜。
• 對話性回覆、解釋概念、改一兩行 → 自己做。
• 判準：已知確切檔案路徑或唯一關鍵字、且預計讀的內容 < 200 行 → 自己做；需要跨多目錄搜尋或猜命名 → 派工。

1. 指揮官不下場

以下工作一律派 subagent，主對話只收結論：

• 大量讀檔／掃 repo／「找出所有用到 X 的地方」→ Explore agent（唯讀，最便宜）
• 查網頁、讀文件、比較方案 → general-purpose agent（可用 WebSearch/WebFetch）
• 批次改檔（同一模式套用到多處）→ general-purpose agent
• 設計實作方案 → Plan agent
• 程式碼審查 → code-reviewer agent（另有 system-architect 做設計層第二輪）

2. 派工三件套（每個派工 prompt 必含，模板見 references/templates.md）

1. 目標與動機：要做什麼、為什麼（讓 agent 遇到岔路能自己判斷）。
2. 驗收條件：可機械檢查的完成定義（例：「編譯通過並貼出 gradle 輸出最後 5 行」，不是「確保品質」）。
3. 回報格式：只回結論 + 檔案:行號；長產物寫到指定路徑，回傳路徑。

3. model 與 effort 的實際可用值（2026-07-03 查證）

• Agent 工具的 model 參數：haiku / sonnet / opus。省略 = 繼承主對話模型，這是預設正解。
• Agent 工具沒有 effort 參數；effort 由 agent 定義的 frontmatter 或 session 的 effortLevel 決定。
• Workflow 工具（多代理編排）並非所有 harness 都有；只在使用者明確要求多代理編排、且工具確實存在時使用。
• 選型基準：
  • haiku：機械性批次套用（模式已驗證過）、格式轉換、簡單 grep 彙整。
  • 省略（=主對話同級）：一般搜尋、實作、審查。
  • opus：架構取捨、難 bug 根因、多方案評審的裁判。
  • 註：升級的終點就是你手上可用的最強層級（本表為 opus）；不要假設還有更高階模型可調度。 最強層級也解不了的品味題/模糊題：向另一個模型家族要第二意見 → 給使用者選項並誠實標明信心低。

4. 回報合約（寫進每個派工 prompt）

• 只回：結論、關鍵證據（檔案:行號、測試輸出末段）、遇到的阻礙。
• 禁止：整檔貼回、逐步過程流水帳。
• 產物超過 ~50 行 → 寫到檔案（scratchpad 或指定路徑），回傳路徑。

5. 升降級路徑

• haiku 錯 1 次 → 直接升級到主對話同級重派，不要對 haiku 講道理。
• 同級 agent 同一子任務連錯 2 次 → 升級到 opus，並把完整失敗軌跡（做了什麼、輸出什麼、為何算失敗）放進新 prompt——不帶軌跡的升級只是換個模型再猜一次。
• 解出模式後：把解法寫成明確步驟，降回 haiku 批次套用到其餘位置。
• 重試上限：同一模型層級內最多 3 次嘗試；升級到新層級時計數歸零。最高層級也用完 3 次 → 停下，照 judgment.md §3 的「該問使用者」處理。

5.5 唯讀/研究任務的副作用邊界（實戰教訓 2026-07-06）

派「研究/審計/唯讀」任務時，prompt 必須界定可執行的驗證命令——「唯讀」不會自動阻止 agent 跑有副作用的命令。

• ❌ 派「研究這專案有什麼可改」不加限制 → agent 為驗證「測試通過」跑 npm test，該專案測試寫正式 DB，研究任務污染了資料。
• ✅ prompt 明列：「只讀原始碼與設定；跑測試/build 前先確認它是否寫正式資源，不確定就回報不執行」。驗證「測試綠不綠」優先讀 CI 記錄或問使用者，而非親跑。

6. 驗證不自驗

適用範圍：委派出去的任務，以及高風險改動（release 路徑、刪東西、公開 API）。主對話自己做的 ≤3 檔小修，自跑編譯/測試並貼輸出即可，不必另派驗收 agent。 做的人不驗自己的活。委派任務的驗收一律派 fresh-context agent（新開，不給它實作過程，只給驗收條件）：

• 檔案類產出 → read-back：新 agent 讀檔，回答「是否包含 X、Y、Z」。
• 程式碼 → 跑測試或實際編譯/執行，貼輸出；沒有測試就寫一個最小重現。
• 高風險判斷（架構、安全、要不要刪東西）→ 第二意見：再派一個 agent 從反方立場審（「試著推翻這個結論」），或多答案評審選優。
• 驗收條件必須含至少一條「實際執行並貼輸出」的項目——只有存在性檢查的驗收單不合格。
• 驗證 agent 說不通過 → 回到實作方（帶著驗證輸出），不要主對話自己「目視覺得沒問題」蓋章。