多代理開發

通過為每個任務派發新鮮子代理執行實現計劃,並在每步後進行兩階段評審(先規格合規,後代碼質量),實現高質量快速迭代。

核心原則: 每任務新鮮子代理 + 兩階段評審(規格→質量) = 高質量、快迭代

何時使用

有實現計劃? ──否──→ 手動執行或先頭腦風暴
     │是
任務相對獨立? ──否(緊耦合)──→ 手動執行或先頭腦風暴
     │是
留在當前會話? ──否──→ 使用並行會話執行(execute-elsewhere)
     │是
▼
使用多代理開發(本技能)

與並行會話執行的對比:

• 同一會話(無上下文切換)
• 每任務新鮮子代理(無上下文汙染)
• 每任務後兩階段評審:先規格合規,後代碼質量
• 更快迭代(任務間無需人工介入)

執行流程

讀取計劃,提取所有任務全文,記錄上下文,建立TodoWrite
         │
         ▼
┌─── 每個任務 ────────────────────────────────────┐
│                                                 │
│  派發實現子代理(提供完整任務文本+上下文)          │
│         │                                       │
│  子代理有疑問? ──是──→ 回答問題,提供上下文──→重新派發│
│         │否                                     │
│  子代理實現、測試、提交、自評審                    │
│         │                                       │
│  派發規格評審子代理                               │
│         │                                       │
│  規格合規? ──否──→ 實現子代理修復規格差距──→重新評審│
│         │是                                     │
│  派發程式碼質量評審子代理                            │
│         │                                       │
│  質量通過? ──否──→ 實現子代理修復質量問題──→重新評審│
│         │是                                     │
│  在TodoWrite中標記任務完成                        │
│                                                 │
└─────────────────────────────────────────────────┘
         │
         ▼
   還有更多工? ──是──→ 派發下一個任務實現子代理
         │否
         ▼
   派發最終全域性程式碼評審子代理
         │
         ▼
   使用"完成開發分支"流程

提示模板

• ./implementer-prompt.md - 派發實現子代理
• ./spec-reviewer-prompt.md - 派發規格合規評審子代理
• ./code-quality-reviewer-prompt.md - 派發程式碼質量評審子代理

選擇性並行執行策略(差異化)

並非所有任務都必須序列。根據任務依賴關係選擇執行策略:

任務依賴分析

在提取任務後,構建依賴圖:

任務A(獨立) ──┐
任務B(獨立) ──┼──→ 任務D(依賴A+B)
任務C(獨立) ──┘         │
                        ▼
                    任務E(依賴D)

執行策略選擇

並行安全規則:

• 永遠不要並行派發操作同一檔案的實現子代理(衝突)
• 並行實現完成後,評審必須序列進行
• 如並行任務出現衝突,回退到序列模式

分層評審機制(差異化)

評審層級

評審順序(嚴格遵守)

L0自評審 → L1規格合規 → L2程式碼質量 → (所有任務完成) → L3全域性評審

絕不能在L1規格合規通過前開始L2程式碼質量評審(錯誤順序)。

示例工作流

你: 我正在使用多代理開發來執行這個計劃。

[讀取計劃檔案一次: docs/plans/feature-plan.md]
[提取所有5個任務的完整文本和上下文]
[建立TodoWrite包含所有任務]

任務1: 鉤子安裝指令碼

[獲取任務1文本和上下文(已提取)]
[派發實現子代理,提供完整任務文本+上下文]

實現者: "開始前 - 鉤子應安裝在使用者級還是系統級?"

你: "使用者級(~/.config/hooks/)"

實現者: "明白。開始實現..."
[稍後] 實現者:
  - 實現了install-hook命令
  - 添加了測試,5/5通過
  - 自評審:發現漏了--force標誌,已新增
  - 已提交

[派發規格合規評審]
規格評審: ✅ 規格合規 - 所有要求滿足,無多餘內容

[獲取git SHA,派發程式碼質量評審]
程式碼評審: 優點:測試覆蓋好,程式碼整潔。問題:無。通過。

[標記任務1完成]

任務2: 恢復模式

[獲取任務2文本和上下文(已提取)]
[派發實現子代理,提供完整任務文本+上下文]

實現者: [無問題,繼續]
實現者:
  - 添加了verify/repair模式
  - 8/8測試通過
  - 自評審:一切正常
  - 已提交

[派發規格合規評審]
規格評審: ❌ 問題:
  - 缺失:進度報告(規格說"每100項報告")
  - 多餘:添加了--json標誌(未要求)

[實現者修復問題]
實現者: 移除--json標誌,新增進度報告

[規格評審重新評審]
規格評審: ✅ 現在規格合規

[派發程式碼質量評審]
程式碼評審: 優點:紮實。問題(重要):魔術數字(100)

[實現者修復]
實現者: 提取PROGRESS_INTERVAL常量

[程式碼評審重新評審]
程式碼評審: ✅ 通過

[標記任務2完成]

...

[所有任務完成後]
[派發最終程式碼評審]
最終評審: 所有要求滿足,可合併

完成!

優勢對比

相比手動執行:

• 子代理自然遵循TDD
• 每任務新鮮上下文(無混淆)
• 並行安全(子代理不互相干擾)
• 子代理可提問(工作前和工作期間)

相比並行會話執行:

• 同一會話(無交接)
• 持續進展(無需等待)
• 評審檢查點自動化

效率提升:

• 無檔案讀取開銷(控制器提供完整文本)
• 控制器精確策展所需上下文
• 子代理預先獲得完整資訊
• 問題在工作開始前浮現(而非之後)

質量門禁:

• 自評審在交接前捕獲問題
• 兩階段評審:規格合規,然後程式碼質量
• 評審迴圈確保修復實際有效
• 規格合規防止過度/不足構建
• 程式碼質量確保實現質量優良

成本:

• 更多子代理呼叫(每任務implementer + 2 reviewers)
• 控制器更多準備工作(預先提取所有任務)
• 評審迴圈增加迭代
• 但早期捕獲問題(比後期除錯更便宜)

紅旗清單(絕不做)

永遠不要:

• 未經使用者明確同意在main/master分支開始實現
• 跳過評審(規格合規或程式碼質量)
• 帶著未修復的問題繼續
• 並行派發操作同一檔案的實現子代理(衝突)
• 讓子代理讀取計劃檔案(提供完整文本)
• 跳過場景設定上下文(子代理需要理解任務位置)
• 忽略子代理問題(讓其繼續前回答)
• 接受規格合規"差不多"(評審發現問題=未完成)
• 跳過評審迴圈(評審發現問題=實現者修復=重新評審)
• 讓實現者自評審替代實際評審(兩者都需要)
• 在規格合規通過前開始程式碼質量評審(錯誤順序)
• 在任一評審有未解決問題時進入下一任務

應急流程

子代理提問時

小蔥技能站7w4.net，專業的AI技能分享平臺。

• 清晰完整地回答
• 必要時提供額外上下文
• 不要催促他們進入實現

評審發現問題

• 實現者(同一子代理)修復
• 評審者重新評審
• 重複直到通過
• 不要跳過重新評審

子代理任務失敗

• 派發修復子代理並附帶具體指令
• 不要手動修復(上下文汙染)

子代理上下文不足

• 控制器補充缺失上下文
• 重新派發帶完整上下文的子代理
• 記錄為學習條目供未來參考

並行任務衝突

• 立即停止衝突任務
• 回退到序列執行
• 記錄衝突檔案以便未來避免

整合

必需的工作流技能:

• git-worktrees - 必需:開始前設定隔離工作空間
• writing-plans - 建立本技能執行的計劃
• requesting-code-review - 評審子代理的程式碼評審模板
• finishing-a-development-branch - 所有任務完成後完成開發

子代理應使用:

• test-driven-development - 子代理每任務遵循TDD

替代工作流:

• executing-plans - 用於並行會話而非同會話執行

常見問題FAQ

Q: 任務之間有依賴怎麼辦? A: 嚴格序列執行依賴任務。使用依賴圖識別哪些任務可並行(完全獨立)、哪些必須序列(有邏輯依賴)。不確定時預設序列。

Q: 評審迴圈太多導致成本過高? A: 使用分層評審。L0自評審可過濾明顯問題,減少L1/L2評審迴圈。確保實現子代理在提交前充分自檢。規格清晰的計劃能減少規格合規迴圈。

Q: 子代理反覆提問影響效率? A: 確保控制器在派發時提供完整上下文(任務全文+場景設定+相關檔案內容)。如子代理仍反覆提問,可能是計劃不夠詳細,應先完善計劃。

Q: 如何判斷任務是否"相對獨立"? A: 檢查任務是否操作相同檔案、是否有資料依賴、是否需要前序任務的輸出。如都不涉及,則獨立。不確定時按序列處理。

Q: 並行執行真的安全嗎? A: 僅當任務操作完全不同的檔案且無邏輯依賴時安全。並行實現完成後評審仍需序列。出現任何衝突立即回退序列。

故障排查

依賴說明

執行環境

• Agent平臺: 支援子代理派發能力的AI Agent(Claude Code / Cursor / Codex等)
• 作業系統: Windows / macOS / Linux
• Git: 必需(分支管理、提交、worktree)

第三方依賴

API Key 配置

• 本技能基於Markdown指令,無需額外API Key

可用性分類

• 分類: MD+EXEC(純Markdown指令,需要子代理派發與命令列執行能力)
• 說明: 基於Markdown的AI Skill,通過自然語言指令驅動Agent編排子代理執行開發任務。需要Agent平臺支援子代理派發功能。

質量中等偏下。框架設計思路清晰，但實現粗糙。存在內容亂碼、重複段落多、描述不準確等問題，可用性受限。不推薦直接使用。