協調 Claude Code 工作階段團隊

​

何時使用 agent teams

• 研究和審查：多個隊友可以同時調查問題的不同方面，然後分享並質疑彼此的發現
• 新模組或功能：隊友可以各自擁有一個獨立部分，不會相互干擾
• 使用競爭假設進行除錯：隊友並行測試不同的理論，更快地收斂到答案
• 跨層協調：跨越前端、後端和測試的變更，各由不同的隊友負責

​

與 subagents 比較

​

啟用 agent teams

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

​

啟動您的第一個 agent team

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

• 向上和向下箭頭：選擇隊友
• Enter：開啟所選隊友的記錄並直接向其傳送訊息
• Escape：中斷所選隊友的目前回合

​

控制您的 agent team

​

選擇顯示模式

• In-process：所有隊友在您的主終端內運行。使用上下箭頭鍵在 agent 面板中選擇隊友，然後按 Enter 鍵查看它並輸入以直接向它傳送訊息。在任何終端中工作，無需額外設定。
• Split panes：每個隊友都有自己的窗格。您可以同時看到所有人的輸出並點擊窗格直接互動。需要 tmux 或 iTerm2。

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• tmux：透過您系統的套件管理器安裝。請參閱 tmux wiki 以了解平台特定的指示。
• iTerm2：安裝 it2 CLI，然後在 iTerm2 → Settings → General → Magic → Enable Python API 中啟用 Python API。

​

指定隊友和模型

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

​

要求隊友的計畫批准

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

​

直接與隊友交談

• In-process 模式：使用上下箭頭鍵在 agent 面板中選擇隊友，然後按 Enter 鍵查看其工作階段並輸入以傳送訊息。在選定的隊友上按 x 以停止它。按 Ctrl+T 切換任務列表。
• Split-pane 模式：點擊隊友的窗格以直接與其工作階段互動。每個隊友都有自己終端的完整檢視。

​

分配和認領任務

• 主管分配：告訴主管將哪個任務分配給哪個隊友
• 自行認領：完成任務後，隊友自行選擇下一個未分配、未阻止的任務

​

關閉隊友

Ask the researcher teammate to shut down

​

使用 hooks 強制執行品質閘門

• TeammateIdle：當隊友即將閒置時運行。以代碼 2 退出以發送反饋並保持隊友工作。
• TaskCreated：當任務正在建立時運行。以代碼 2 退出以防止建立並發送反饋。
• TaskCompleted：當任務被標記為完成時運行。以代碼 2 退出以防止完成並發送反饋。

​

Agent teams 如何工作

​

Claude 如何啟動 agent teams

• 您請求隊友：給 Claude 一個受益於並行工作的任務，並明確要求隊友。Claude 根據您的指示生成他們。
• Claude 提議隊友：如果 Claude 確定您的任務將受益於並行工作，它可能會建議生成隊友。您在它繼續之前確認。

​

架構

• Team config：~/.claude/teams/{team-name}/config.json
• Task list：~/.claude/tasks/{team-name}/

​

為隊友使用 subagent 定義

Spawn a teammate using the security-reviewer agent type to audit the auth module.

​

權限

​

Context 和通訊

• 自動訊息傳遞：當隊友發送訊息時，它們會自動傳遞給收件人。主管不需要輪詢更新。
• 閒置通知：當隊友完成並停止時，他們會自動通知主管。自 v2.1.198 起，隊友的回合因 API 錯誤而結束時會通知主管它失敗並包含錯誤文本，而不是看起來正常完成。
• 共享任務列表：所有代理都可以看到任務狀態並認領可用工作。
• 隊友訊息傳遞：按名稱向一個特定隊友發送訊息。若要聯繫所有人，請為每個收件人發送一條訊息。

​

Token 使用

​

使用案例範例

​

運行並行程式碼審查

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

​

使用競爭假設進行調查

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

​

最佳實踐

​

給隊友足夠的 context

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

​

選擇適當的團隊規模

• Token 成本線性增加：每個隊友都有自己的 context window 並獨立消耗 tokens。請參閱 agent team token 成本以了解詳情。
• 協調開銷增加：更多隊友意味著更多通訊、任務協調和潛在衝突
• 收益遞減：超過一定點後，額外的隊友不會按比例加快工作

​

適當調整任務大小

• 太小：協調開銷超過收益
• 太大：隊友工作時間過長而沒有檢查點，增加浪費努力的風險
• 恰到好處：自包含的單位，產生清晰的可交付成果，例如函數、測試檔案或審查

​

等待隊友完成

Wait for your teammates to complete their tasks before proceeding

​

從研究和審查開始

​

避免檔案衝突

​

監控和引導

​

故障排除

​

隊友未出現

• 在 in-process 模式中，隊友會出現在提示輸入下方的代理面板中。使用上下箭頭鍵選擇一個，然後按 Enter 鍵查看它。
• 閒置後消失的隊友列已被隱藏，而非停止。閒置列在整個面板閒置 30 秒後隱藏，並在隊友的下一輪時重新出現。當超過三個隊友閒置時，其多餘列會摺疊成單一的 N idle agents 列，按 Enter 鍵可展開。按名稱向隊友發送訊息以將隱藏列恢復。
• 檢查您給 Claude 的任務是否足夠複雜以保證建立團隊。Claude 根據任務決定是否生成隊友。
• 如果您明確要求分割窗格，請確保 tmux 已安裝並在您的 PATH 中可用：
  which tmux
  
• 對於 iTerm2，驗證 it2 CLI 已安裝且 Python API 在 iTerm2 偏好設定中啟用。

​

過多權限提示

​

隊友在錯誤時停止

• 直接給他們額外的指示
• 生成替換隊友以繼續工作

​

主管在工作完成前關閉

​

孤立的 tmux 工作階段

tmux ls
tmux kill-session -t <session-name>

​

限制

• 沒有 in-process 隊友的工作階段恢復：/resume 和 /rewind 不會恢復 in-process 隊友。恢復工作階段後，主管可能會嘗試向不再存在的隊友傳送訊息。如果發生這種情況，告訴主管生成新隊友。
• 任務狀態可能滯後：隊友有時無法將任務標記為已完成，這會阻止依賴任務。如果任務似乎卡住，請檢查工作是否實際完成並手動更新任務狀態或告訴主管推動隊友。
• 關閉可能很慢：隊友在關閉前完成其目前請求或工具呼叫，這可能需要時間。
• 每個工作階段一個團隊：一個工作階段恰好有一個團隊，範圍限於該工作階段。您無法建立其他具名團隊或在工作階段之間共享團隊。
• 沒有嵌套團隊：隊友無法生成自己的隊友。只有主管可以管理團隊。
• 沒有來自 in-process 隊友的背景子代理：in-process 隊友自己的子代理在前景中執行。要求背景子代理，無論是使用 run_in_background 或設定 background: true 的子代理定義，都會傳回錯誤，因為隊友的背景工作無法超越主管的程序。從主要對話啟動的子代理遵循背景預設。
• 主管是固定的：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。
• 權限在生成時設定：所有隊友開始時具有主管的權限模式。您可以在生成後更改個別隊友模式，但在生成時無法設定每個隊友的模式。
• 分割窗格需要 tmux 或 iTerm2：預設 in-process 模式在任何終端中工作。VS Code 的整合終端、Windows Terminal 或 Ghostty 不支援分割窗格模式。

​

後續步驟

• 輕量級委派：subagents 在您的工作階段內為研究或驗證生成幫助代理，更適合不需要代理間協調的任務
• 手動並行工作階段：Git worktrees 讓您自己運行多個 Claude Code 工作階段，無需自動化團隊協調
• 比較方法：請參閱 subagent vs agent team 比較以了解並排細分