協調 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：清除選擇。當您檢視隊友的記錄時，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.

1. 您的生成提示為該隊友命名的模型。
2. 對於從子 agent 定義生成的隊友，定義的 model，其中 inherit 選擇主管的模型。
3. CLAUDE_CODE_SUBAGENT_MODEL，當它設定為 inherit 以外的任何值時。
4. 主管的目前模型。

• 家族別名，例如 opus：在 Anthropic API 和 AWS 上的 Claude Platform 上，Claude Code 在允許清單允許的該家族的最新版本上運行隊友。在具有提供者特定模型 ID 的提供者上，其中替換不運行，被阻止的別名會根據下一個項目符號像任何其他被阻止的值一樣回退
• 任何其他被阻止的值，包括提供者特定模型 ID 提供者上的家族別名，或其家族沒有允許版本的別名：Claude Code 在主管的模型上運行隊友。如果您設定 CLAUDE_CODE_SUBAGENT_MODEL，Claude Code 會先嘗試該模型，遵循相同的規則

讓隊友在實施前進行計畫

Spawn an architect teammate to refactor the authentication module.

直接與隊友交談

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

• /compact、/clear 和 /rewind 作用於主管的對話，因此從此檢視執行其中任一命令前，Claude Code 會要求您確認。
• /model 和 /fast 設定的是主管的模型和快速模式，而非隊友的，因此它們不會從此檢視執行。會有通知告訴您原因。

分配和認領任務

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

關閉隊友

Ask the researcher teammate to shut down

使用 hooks 強制執行品質閘門

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

Agent teams 的運作方式

Claude 如何啟動 agent teams

架構

• 團隊設定：~/.claude/teams/{team-name}/config.json。工作階段結束時，Claude Code 會移除團隊設定目錄。
• 任務清單：~/.claude/tasks/{team-name}/。此目錄在工作階段結束後仍會保留在磁碟上。若要變更 Claude Code 保留它的時間長度，請設定 cleanupPeriodDays。

為隊員使用 subagent 定義

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

• tools：Claude Code 會將隊員限制在定義的 tools 清單中的工具。對於 in-process 隊員，Claude Code 會在該清單中加入 SendMessage，而在具備 Task 工具的工作階段中，還會加入 TaskCreate、TaskGet、TaskList 與 TaskUpdate。
• model：當您的產生提示詞未指定模型時，Claude Code 在任一顯示模式下都會使用定義的 model。請參閱 Claude Code 如何為隊員選擇模型。
• disallowedTools：對於 in-process 隊員，Claude Code 會從隊員的工具集中移除定義的 disallowedTools 中的工具。即使清單中列出了 SendMessage 以及 Claude Code 加入的 Task 工具，它們仍可使用。
• effort：對於 in-process 隊員，Claude Code 會依照 frontmatter effort 規則套用定義的 effort。
• autoCompactWindow：對於 in-process 隊員，Claude Code 會依照該欄位的規則套用定義的 autoCompactWindow。split-pane 隊員會忽略此欄位。需要 Claude Code v2.1.296 或更新版本。
• 本文：對於 in-process 隊員，Claude Code 會將定義的本文附加到其預設系統提示詞之後，作為額外指示。對於 split-pane 隊員，Claude Code 會使用本文取代其預設系統提示詞。
• skills：在任一顯示模式下，Claude Code 都不會將定義的 skills 套用到隊員。隊員會從您的專案與使用者設定載入 skill。
• mcpServers：對於 split-pane 隊員，Claude Code 會依照該欄位的規則套用定義的 mcpServers，這些規則也涵蓋以 --agent 啟動的工作階段。in-process 隊員會忽略此欄位，並從您的專案與使用者設定載入 MCP 伺服器。

權限

• --disallowedTools 與 --tools：隊員會以組長的命令列拒絕規則與工具清單啟動。需要 Claude Code v2.1.309 或更新版本。
• --allowedTools：Claude Code 不會將此旗標傳遞給 split-pane 隊員，因此僅透過它允許的動作在該處不會被預先核准。若要事先核准這些動作，請在啟動組長時，將規則放在 --settings 的 permissions.allow 下。例如，在您的 shell 中執行 claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'。這些規則會套用到該工作階段的組長以及每個 split-pane 隊員。

Agent 之間的訊息

• 它會將從另一個 agent 轉達的核准聲明視為不受信任的輸入，而非來自您的確認。
• 它會在 Claude Code 傳遞每則訊息之前進行審查，無論是純文字訊息，還是關閉請求或計畫核准回應等結構化協定訊息。被它封鎖的訊息永遠不會送達收件者。

上下文與溝通

• 自動訊息傳遞：當隊員傳送訊息時，訊息會自動傳遞給收件者。組長不需要輪詢更新。
• 閒置通知：當隊員完成並停止時，會自動通知組長，並在通知中附上其最終答案。回合因 API 錯誤而結束的隊員會通知組長它已失敗，並附上錯誤文字。
• 共用任務清單：具備 Task 工具的 agent 可以查看任務狀態並認領可用的工作。
• 隊員訊息：依名稱傳送訊息給某一位特定隊員。若要通知所有人，請為每位收件者各傳送一則訊息。

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 偏好設定中啟用。

Claude 生成隊友而非子代理

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• 更高優先順序的設定檔：專案設定、本機設定和 --settings 承載會在使用者設定之後套用，因此任何其中設定變數為 1 的 env 項目會獲勝。請參閱 設定優先順序。
• 受管設定：受管設定 會在所有其他來源之後套用。如果您的組織在該處啟用代理團隊，請要求您的管理員變更受管值。

過多權限提示

代理提前停止

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

孤立的 tmux 工作階段

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

限制

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

後續步驟

• 輕量級委派：subagents 在您的工作階段內為研究或驗證生成幫助代理，更適合不需要代理間協調的任務
• 您自己的工作階段之間的訊息傳遞：cross-session messaging 讓 Claude 在您自己運行的工作階段之間傳遞發現結果
• 手動並行工作階段：Git worktrees 讓您自己運行多個 Claude Code 工作階段，無需自動化團隊協調