Claude Code Agent Teams 怎麼用：Team Lead、點對點傳訊與共享任務板

🌏 English version

這是「Claude Code 深入介紹」系列的 Agent Teams 篇。F1 多代理全景畫過整張地圖，D4 sub-agents 講過最輕量的平行方式；這篇處理的是重量級選項——多個 Claude Code instance 組成一個長期共存的團隊。功能目前是實驗性質，預設關閉，官方文件也明白列出已知限制，所以這篇一半在講怎麼用，一半在講什麼時候不該用。

跟 Sub-agent 的差別在哪裡

Sub-agent 是「派工後收報告」：主對話開一個新的 context window，sub-agent 做完把結果摘要回傳，生命週期就結束了。Agent Teams 的 teammates 不一樣，他們是長期存在的完整 Claude Code session——各自有自己的 context window，spawn 時載入同一份 CLAUDE.md、MCP servers 和 skills，但不繼承 lead 的對話歷史。

官方文件的比較是這樣（sub-agent 的完整機制另見官方 sub-agents 文件）：

歸納成三句話：Agent Teams 把長期共存的 teammates、共享任務板、以及你直接切進任一 teammate 對話這三件事包成一個協作模式。互傳訊息本身已不再是 Agent Teams 獨有，差別在它和任務板、lead 協調一起運作。

怎麼開一個 Team

Agent Teams 由 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 控制，預設關閉。在 settings.json 加上：

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

v2.1.178 之後不需要再叫 Claude 建 team、取名——直接用自然語言描述任務和你想要的 teammates 就好：

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Claude 會填共享任務清單、逐一 spawn teammates、等大家做完再彙整。

一個副作用要知道：這個變數打開之後，Claude 自己命名的 subagent 也會以 teammate 的形式啟動，即使你沒有要求組隊。如果某段流程其實只需要 subagent 的「做完回報」，把變數設回 "0" 即可，不用重開 session。另外非互動模式（-p flag、Agent SDK）不會 spawn teammates。

Team Lead 與 Teammates 各自做什麼

架構上只有四個零件：

資料都放在本機：team config 在 ~/.claude/teams/{team-name}/config.json，任務在 ~/.claude/tasks/{team-name}/。team 名稱由 session ID 衍生（session- 加前八碼），session 結束時 config 自動清除，任務清單則保留，讓 resume 之後的 session 還接得上。

分工的核心原則：你對 lead 下指令，lead 對 teammates 下指令。複雜或有風險的任務可以加一道 plan approval——要求 teammate 先待在唯讀 plan mode 提出計畫，等 lead session 批准後才開始實作。這裡不要誤會成有人替你審稿：官方文件寫明 approval request 到 lead session 後會直接批准，不會另行審核；真正的保護仍是後續 edit 和 command 的 permission prompts。

權限方面，teammates 繼承 lead 的 permission settings，spawn 之後可以個別調整，但不能在 spawn 當下分別指定；teammate 的權限提示會浮到 lead session 由你處理。

傳訊模型：點對點，沒有 broadcast

Teammates 之間用 SendMessage 傳訊，只能點名：要通知所有人，就是一人一則。官方文件的原話是「To reach everyone, send one message per recipient」——沒有 broadcast 這種操作。

訊息自動送達，lead 不需要輪詢。Teammate 做完停下來時會送 idle 通知給 lead，但通知不帶輸出內容——結果本身要靠 teammate 傳訊或更新任務清單來分享。

底層是每個代理一個 mailbox JSON 檔（~/.claude/teams/{team-name}/inboxes/{agent-name}.json），寫入成功才算送出。安全規則值得記住：收件方會被告知訊息來自另一個 Claude session 而不是你，所以 teammate 不能替你核准權限，被拒絕的動作也不能轉手請另一個 teammate 放行。

工具層面的現況：SendMessage 負責代理間傳訊（也能傳給你其他的 Claude Code session，v2.1.224 起）；ListAgents 列出所有可傳訊的對象，同樣需要 v2.1.224 以上，且只在啟用 cross-session messaging 的 session 出現。

任務板管理

共享任務清單由四個工具撐起來：TaskCreate、TaskGet、TaskList、TaskUpdate。任務有三種狀態：pending → in progress → completed。依賴會自動管理——pending 任務的依賴還沒完成就不能認領，teammate 完成一項任務時，下游任務自動解鎖，不用你動手。

指派有兩條路：

• Lead 指派：告訴 lead 哪個任務給哪個 teammate。
• Self-claim：teammate 做完手上的事，自己挑下一個未被指派、未被阻塞的任務。

認領用 file locking，避免兩個 teammate 同時搶同一個任務。想掛品質閘門就用 hooks：TeammateIdle（teammate 快要閒置時）、TaskCreated、TaskCompleted 三個事件，exit code 2 都能擋下並回饋意見。

操作面上，按 Ctrl+T 切換任務清單顯示；agent panel 用上下方向鍵選取 teammate，Enter 打開 transcript 並直接傳訊，選取後按 x 停止 teammate。Esc 先清掉選取；如果你正在看某個 teammate 的 transcript，Esc 會中斷該 teammate 目前的回合。

teammateMode：兩種顯示模式

• In-process（預設）：所有 teammates 跑在你主終端機裡，靠 agent panel 切換。任何 terminal 都能用，零額外設定。
• Split panes：每個 teammate 一個 pane，一眼看到所有輸出、點進去直接互動。需要 tmux 或 iTerm2。

設定用 ~/.claude/settings.json 的 teammateMode，可選 "in-process"、"auto"（已在 tmux session 或裝好 it2 CLI 的 iTerm2 就開分割，否則退回 in-process）、"tmux"（啟用 split-pane，並依終端機自動判斷用 tmux 或 iTerm2）、"iterm2"（v2.1.186 起，明確使用 iTerm2 原生分割，需要 it2 CLI）。注意預設值的演變：v2.1.179 起預設從 "auto" 改成 "in-process"，舊版習慣開分割的人要自己設回去。單次 session 可以用 claude --teammate-mode auto 覆蓋（實驗性 flag，不出現在 --help）。

檢視 in-process teammate 時，你打的純文字和 skills 會送給那個 teammate，但內建指令仍在 lead session 執行。另外 teammate 的 model 和 fast mode 在 spawn 當下就固定了——/model 和 /fast 只改 lead 的設定；/effort 則會套用到目前檢視的 teammate 後續回合。

適用場景與成本警告

官方點名的四個強項場景：research & review（多人從不同角度審查、互相挑戰結論）、新模組開發（各管一塊檔案不打架）、競爭假設除錯（五個 teammates 互相駁倒對方的理論，活下來的那個最可能是真因）、跨層協調（前端、後端、測試各一個）。新手建議先從不寫 code 的任務開始驗證價值。

反面清單同樣明確：循序任務、同檔案編輯、依賴關係多的工作，用單一 session 或 subagents 比較有效率。

成本是最現實的剎車：每個 teammate 一個獨立 context window，token 用量隨人數線性上升，官方明說比單一 session 貴得多。官方建議多數 workflow 先從 3 到 5 個 teammates 起步；如果有 15 個獨立任務，3 個 teammates 通常是合理起點，三個專注的 teammates 常常贏過五個分散的。已知限制也要列入決策：in-process teammates 不支援 /resume 和 /rewind 還原、任務狀態更新可能延遲、關閉 teammate 可能很慢、一個 session 只能有一個 team、teammates 不能再 spawn 自己的 teammates、lead 固定不可轉移，split-pane 也不支援 VS Code integrated terminal、Windows Terminal 或 Ghostty。

學到的事

Sub-agent 是函式呼叫，agent team 是共事的同事——差別不在「能不能平行」（兩者都能），而在協調方式和生命週期：teammates 長期共存、可以被你直接切入對話、並靠共享任務板自我協調。代價是 token 成本線性上升加上實驗期的不穩定。我的建議：先用 review 或 research 這類邊界清楚的任務試一次團隊運作，確認協調收益真的超過成本，再把寫 code 的分工交給它。

參考資料

• Orchestrate teams of Claude Code sessions — Claude Code Docs — Agent Teams 官方文件：啟用方式、顯示模式、任務板、mailbox 架構、hooks、限制與 troubleshooting 的第一手來源
• Tools reference — Claude Code Docs — SendMessage／ListAgents／TaskCreate 等 Task 工具的現況、版本需求與權限欄位
• Create custom subagents — Claude Code Docs — Sub-agent 的生命週期、工具過濾與「單一 session 內運作」的定位，Agent Teams 比較表的對照基準
• Message your other Claude Code sessions — Claude Code Docs — cross-session messaging、ListAgents 可見範圍、訊息安全邊界與版本需求
• Manage costs effectively — Claude Code Docs — Agent Teams token 成本、team size 與控制成本的官方建議

更新紀錄

• 2026-03-28：建立大綱骨架。
• 2026-08-26：展開為正文，依官方文件（code.claude.com，含 v2.1.178+ 行為）全面重寫；修正切換 teammate 的操作為方向鍵選取＋Enter、移除不存在的 broadcast 描述、補上 teammateMode "iterm2" 與 SendMessage／ListAgents 工具現況。
• 2026-08-29：對齊官方 Agent Teams 文件現況：修正 plan approval 會由 lead session 直接批准、補 x 停止 teammate、更新 subagent messaging 與 teammateMode 說法。