代理模式
概述
代理模式定義了 Sprint 外掛程式中多代理衝刺執行的協調協議。它規範了專案架構師如何生成實作與測試代理，代理如何透過結構化報告溝通結果，以及平行代理如何避免衝突。
前置需求
- 已安裝並設定 Sprint 外掛程式 (
/plugin install sprint) - 已在
.claude/sprint/[N]/初始化 Sprint 目錄 - 已撰寫
specs.md，包含明確範圍與測試設定 - 熟悉衝刺階段生命週期（請參閱
sprint-workflow技能）
指示
- 使用 SPAWN REQUEST 格式結構化每個代理生成。包含代理名稱、應讀取的規格檔案以及任何範圍限制：
SPAWN REQUEST Agent: python-dev Specs: .claude/sprint/1/backend-specs.md Contract: .claude/sprint/1/api-contract.md Scope: Authentication endpoints only - 確保每個生成的代理僅接收與其範圍相關的檔案。傳遞
api-contract.md作為共享介面，以便後端與前端代理保持同步。 - 在每個代理完成後收集結構化報告。每份報告必須包含：完成的工作、修改的檔案、新增的測試，以及相對於規格的符合狀態。
- 當平行執行代理時，按領域邊界劃分工作（例如後端 vs. 前端 vs. CI/CD）。切勿將重疊的檔案路徑分配給並行代理。
- 將代理報告回饋給專案架構師進行審查。架構師決定是否要迭代（以縮小的規格重新生成）或進入下一階段。
- 對於測試代理，傳遞
${CLAUDE_SKILL_DIR}/references/ui-test-report.md中顯示的 UI 測試報告格式，使結果遵循一致的架構，包含測試計數、涵蓋率、失敗與主控台錯誤。
輸出
- 由衝刺協調器消費以啟動代理的 SPAWN REQUEST 區塊
- 結構化代理報告，包含：摘要、修改的檔案、測試結果與符合狀態
- 包含通過/失敗計數、涵蓋率詳細資訊、失敗描述與主控台錯誤日誌的 UI 測試報告
- 每次迭代後反映已完成與剩餘工作的更新
status.md
錯誤處理
| 錯誤 | 原因 | 解決方案 |
|---|---|---|
| 代理接收錯誤的規格檔案 | SPAWN REQUEST 中的路徑不正確 | 在生成前驗證衝刺目錄編號與檔案名稱 |
| 平行代理的檔案修改重疊 | 範圍邊界未明確定義 | 按領域劃分工作；為每個代理分配不同的目錄 |
| 代理報告缺少必要欄位 | 代理指示缺少報告格式 | 在代理提示中包含結構化報告範本 |
| 無限迭代迴圈 | 規格從未完全滿足 | 檢查 status.md 以找出阻礙問題；協調器在 5 次迭代後暫停 |
| 找不到代理 | SPAWN REQUEST 中的代理名稱拼寫錯誤 | 驗證代理 markdown 檔案存在於 agents/ 目錄中 |
範例
生成平行實作代理：
SPAWN REQUEST
Agent: python-dev
Specs: .claude/sprint/1/backend-specs.md
Contract: .claude/sprint/1/api-contract.md
SPAWN REQUEST
Agent: nextjs-dev
Specs: .claude/sprint/1/frontend-specs.md
Contract: .claude/sprint/1/api-contract.md
兩個代理共用同一個 api-contract.md 以確保 API 相容性。
結構化代理報告格式：
AGENT REPORT
Agent: python-dev
Status: COMPLETE
Files Modified: src/auth/routes.py, src/auth/models.py, tests/test_auth.py
Tests: 12 passed, 0 failed
Conformity: All backend-specs requirements implemented
Notes: JWT token expiry set to 24h per spec
測試代理協調：
SPAWN REQUEST
Agent: qa-test-agent
Specs: .claude/sprint/1/specs.md
Run After: python-dev, nextjs-dev
SPAWN REQUEST
Agent: ui-test-agent
Specs: .claude/sprint/1/specs.md
Run After: qa-test-agent
資源
${CLAUDE_SKILL_DIR}/references/ui-test-report.md-- 包含涵蓋率與失敗追蹤的結構化 UI 測試報告格式- 衝刺工作流程技能，提供階段生命週期上下文
- API 合約技能，用於共享介面設計
- Sprint 外掛程式 README，提供代理架構總覽