第 18 課：代理團隊與隊友
學習目標
完成本課程後，您將能夠：
- 瞭解什麼是代理團隊以及何時使用
- 設定分割窗格協作（tmux、WezTerm、iTerm2）
- 建立和管理代理團隊
- 使用 spawnTeam 功能
- 啟用隊友通訊模式
- 疑難排解代理團隊問題（2.1.33 已修正）
先決條件
- 已完成第 1-17 課 - 核心操作與多代理概念
- 熟悉 tmux、WezTerm 或 iTerm2 - 用於分割窗格工作流程
- 多代理經驗 - 建議先完成第 14 課
- 適當的訂閱方案 - 代理團隊需要特定訂閱層級
預估時間： 40 分鐘
什麼是代理團隊？
代理團隊允許多個 Claude Code 實例在分割窗格終端機中協作，即時合作完成同一項任務。
概念：並肩工作的隊友
將代理團隊想像為開發人員的配對程式設計：
┌─────────────────┬─────────────────┐
│ 隊友 1 │ 隊友 2 │
│ （後端開發） │ （前端開發） │
│ │ │
│ 處理中 │ 處理中 │
│ API 端點 │ UI 元件 │
└─────────────────┴─────────────────┘
│ │
└─────────┬─────────┘
│
通訊頻道
主要好處：
- 視覺化協作 - 即時看到隊友工作
- 專業分工 - 每個隊友專注於一個領域
- 直接通訊 - 隊友之間互傳訊息
- 並行執行 - 同時執行多項任務
- 共享情境 - 所有隊友存取相同專案
何時使用代理團隊
最佳使用情況：
- 全端開發 - 前端與後端同時工作
- 微服務 - 同時更新多個服務
- 程式碼審查 - 一名隊友審查，另一名實作
- 測試與開發 - 一人撰寫測試，一人實作功能
- 文件與程式碼 - 一人撰寫文件，一人撰寫程式碼
- 多語言專案 - 不同隊友處理不同語言
何時不使用：
- 簡單的單一檔案變更
- 快速查詢或查閱
- 無法並行化的線性任務
設定分割窗格協作
代理團隊透過分割窗格終端機運作。在 2.1.33 版中，Claude Code 支援：
支援的終端機
-
tmux（最常見）
- 在 Linux、macOS、Windows (WSL) 上運作
- 強大的終端機多工器
- 需要組態
-
WezTerm（2.1.33 新增！）
- 現代 GPU 加速終端機
- 跨平台（Windows、macOS、Linux）
- 已修正隊友工作階段通訊
-
iTerm2（僅 macOS）
- 功能豐富的 macOS 終端機
- 原生分割窗格支援
- 已修正隊友工作階段通訊
為代理團隊組態 tmux
步驟 1：安裝 tmux
# macOS
brew install tmux
# Ubuntu/Debian
sudo apt-get install tmux
# Fedora
sudo dnf install tmux
步驟 2：組態 tmux
建立或編輯 ~/.tmux.conf：
# 啟用滑鼠控制
set -g mouse on
# 使用 C-a 作為前綴（可選，比 C-b 更舒適）
unbind C-b
set -g prefix C-a
bind C-a send-prefix
# 使用 | 和 - 分割窗格
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"
# 使用 Alt-arrow 鍵切換窗格（無需前綴）
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D
# 輕鬆循環切換窗格
bind -r C-a select-pane -t :.+
步驟 3：啟動 tmux
tmux new-session -s claude-team
組態 WezTerm（2.1.33 新增！）
步驟 1：安裝 WezTerm
從以下網址下載：https://wezfurlong.org/wezterm/
步驟 2：組態 WezTerm
編輯 ~/.wezterm.lua：
local wezterm = require('wezterm')
local config = {}
config.keys = {
-- 水平分割
{
key = '|',
mods = 'CTRL|SHIFT',
action = wezterm.action.SplitHorizontal {
domain = 'CurrentPaneDomain',
},
},
-- 垂直分割
{
key = '-',
mods = 'CTRL|SHIFT',
action = wezterm.action.SplitVertical {
domain = 'CurrentPaneDomain',
},
},
}
return config
驗證終端機支援
您> 檢查我的終端機是否支援代理團隊
Claude：我將檢查您的終端機組態。
[Bash 代理檢查環境]
Claude：您的終端機組態如下：
- 終端機：tmux 3.3a
- 分割支援：是
- 隊友模式：可用
代理團隊將在您目前的工作階段中正常運作。
建立代理團隊
方法 1：使用 spawnTeam 工具
spawnTeam 工具建立一組在分割窗格中工作的隊友。
基本團隊建立：
您> 建立一個 2 人團隊來協助重構這個程式庫
Claude：我將產生一個 2 人團隊來協助重構。
[產生隊友...]
tmux：分割成 3 個窗格（1 個主要 + 2 個隊友）
團隊組態：
┌─────────────┬─────────────┬─────────────┐
│ 主要（您） │ 隊友 1 │ 隊友 2 │
│ 協調 │ 後端 │ 前端 │
└─────────────┴─────────────┴─────────────┘
隊友 1：專注於後端 API 重構
隊友 2：專注於前端元件更新
所有隊友都可以通訊和協調。
方法 2：設定檔組態
在 settings.json 中組態團隊：
{
"agentTeams": {
"fullstack": {
"name": "全端團隊",
"teammates": [
{
"name": "backend",
"agentType": "general-purpose",
"model": "claude-sonnet-4-5",
"systemPrompt": "你是一名後端開發人員。專注於 API 設計、資料庫操作和伺服器端邏輯。使用 TypeScript 和 Express。"
},
{
"name": "frontend",
"agentType": "general-purpose",
"model": "claude-sonnet-4-5",
"systemPrompt": "你是一名前端開發人員。專注於 UI 元件、狀態管理和使用者體驗。使用 React 和 TypeScript。"
}
]
}
}
}
使用已組態的團隊：
您> 產生全端團隊
Claude：我將產生全端團隊。
[從設定載入團隊組態]
團隊：全端團隊
- 後端隊友（claude-sonnet-4-5）
- 前端隊友（claude-sonnet-4-5）
設定分割窗格環境...
TeammateMode 設定
在 settings.json 中組態隊友的顯示方式：
{
"teammateMode": "tmux"
}
選項：
"tmux"- 使用 tmux 分割窗格（Linux、macOS、WSL）"iterm2"- 使用 iTerm2 分割窗格（僅 macOS）"wezterm"- 使用 WezTerm 分割窗格（跨平台）"in-process"- 無分割窗格，隊友在背景執行
隊友通訊
團隊成員可以使用 SendMessage 工具進行通訊。
通訊模式
1. 主要代理 → 隊友
您（主要）：告訴後端隊友實作使用者認證端點
Claude：我將傳送訊息給後端隊友。
[透過 SendMessage 傳送訊息]
隊友（後端）：我將實作使用者認證端點。
[後端隊友開始處理認證端點...]
2. 隊友 → 主要代理
隊友（後端）：我已完成認證端點。前端隊友，請整合它。
[透過 SendMessage 傳送]
Claude（主要）：後端已完成認證端點。
轉發請求給前端隊友...
隊友（前端）：我現在將整合認證端點。
3. 隊友 ↔ 隊友
隊友（後端）：前端，我需要 API 回應的使用者 ID 格式。
隊友（前端）：我們需要 UUID 格式：{ "id": "uuid", "email": "..." }
隊友（後端）：知道了，現在更新回應格式。
監控隊友活動
在他們的分割窗格中觀看隊友正在做什麼：
┌───────────────────┬───────────────────┬───────────────────┐
│ 主要：協調中 │ 後端：工作中 │ 前端：閒置 │
│ │ │ │
│ Claude：後端， │ 隊友：正在讀取 │ 隊友：等待中... │
│ 更新 API │ src/api/auth.ts │ 等待後端... │
│ │ │ │
│ [情境顯示 │ [情境顯示 │ [情境顯示 │
│ 所有隊友] │ 認證檔案] │ 元件檔案] │
└───────────────────┴───────────────────┴───────────────────┘
實作範例：全端功能
讓我們使用代理團隊建立完整功能。
情境：使用者認證功能
任務： 實作具有後端 API 和前端 UI 的使用者註冊和登入。
步驟 1：建立團隊
您> 建立一個全端團隊來實作使用者認證
Claude：我將產生一個 2 隊友全端團隊。
[在分割窗格中產生隊友]
團隊結構：
┌────────────┬──────────────┬──────────────┐
│ 您（主要） │ 後端 │ 前端 │
│ │ 隊友 │ 隊友 │
└────────────┴──────────────┴──────────────┘
步驟 2：分配任務
您> 後端隊友，實作註冊和登入 API 端點。
前端隊友，建立登入和註冊表單。
Claude：我將傳送這些任務給兩位隊友。
[傳送訊息...]
步驟 3：觀察協作
後端窗格：
隊友（後端）：我將實作認證 API 端點。
[建立 src/api/auth.ts]
- POST /api/auth/register
- POST /api/auth/login
- GET /api/auth/me
[實作驗證和 JWT token]
前端窗格：
隊友（前端）：我將建立認證 UI 元件。
[建立 components/LoginForm.tsx]
[建立 components/RegisterForm.tsx]
[實作表單驗證]
步驟 4：協調整合
隊友（後端）：前端，API 已準備好在：
- POST /api/auth/register
- POST /api/auth/login
請求內容：{ "email": string, "password": string }
回應：{ "token": string, "user": {...} }
隊友（前端）：收到了！現在與 API 整合。
[前端更新以呼叫後端端點]
步驟 5：主要代理協調
您：兩位隊友，請測試完整流程
[兩位隊友執行測試]
後端：所有 API 測試通過 ✓
前端：UI 整合正常運作 ✓
Claude：認證功能已完成！
疑難排解（2.1.33 修正）
常見問題與解決方案
問題 1：「代理團隊在您目前的方案上不可用」
此警告出現在您的訂閱未包含代理團隊時。
解決方案：
- 代理團隊需要特定的訂閱層級
- 在
/usage或/status檢查您的方案 - 如需請升級
問題 2：隊友無法傳送/接收訊息（2.1.33 已修正！）
先前版本的 tmux 隊友通訊有問題。
2.1.33 已修正：
- tmux 中的隊友工作階段現在可以正確傳送和接收訊息
- 新增 WezTerm 支援用於分割窗格隊友
- 已修正 iTerm2 隊友通訊
問題 3：隊友以行程內模式執行而不是分割窗格
原因： 終端機不支援分割窗格或未設定 teammateMode。
解決方案：
- 檢查終端機支援：
/doctor - 在設定中設定
teammateMode：{
"teammateMode": "tmux" // 或 "wezterm", "iterm2"
} - 重新啟動 Claude Code
問題 4：iTerm2 靜默回退到行程內模式
原因： 在 tmux 內時未偵測到 iTerm2 CLI。
解決方案：
- 不要在 tmux 內執行 tmux
- 直接在 iTerm2 中啟動 Claude Code（不在 tmux 內）
- 或使用 tmux 作為主要終端機
最佳實踐
1. 角色專業化
為每個隊友指定清楚、專注的角色：
{
"agentTeams": {
"microservices": {
"teammates": [
{
"name": "auth-service",
"systemPrompt": "你只處理認證服務。專注於安全性、JWT 處理和使用者管理。"
},
{
"name": "data-service",
"systemPrompt": "你只處理資料服務。專注於資料庫操作、查詢和資料驗證。"
},
{
"name": "api-gateway",
"systemPrompt": "你只處理 API 閘道。專注於路由、速率限制和請求編排。"
}
]
}
}
}
2. 通訊協定
建立清楚的通訊模式：
後端 → 前端：「API 就緒」模式
1. 後端完成端點
2. 傳送訊息與端點文件
3. 前端確認並整合
前端 → 後端：「API 請求」模式
1. 前端需要新端點
2. 傳送訊息與需求
3. 後端確認並實作
3. 情境共享
使用共享情境檔案：
<!-- .claude/team-context.md -->
# 團隊情境
## API 端點
- POST /api/users - 建立使用者
- GET /api/users/:id - 取得使用者
- PUT /api/users/:id - 更新使用者
## 資料模型
User：{ id, email, name, createdAt, updatedAt }
## 團隊職責
- 後端：API 實作、資料庫
- 前端：UI 元件、API 整合
所有隊友都可以參考此檔案。
4. 一起測試
讓隊友測試彼此的工作：
後端：我已實作使用者端點。你能測試嗎？
前端：現在測試...
[前端執行整合測試]
前端：所有測試通過！做得好。
後端：謝謝！準備好下一個任務。
✅ 檢查您的理解
-
哪些終端機支援代理團隊？
- 只有 tmux
- tmux、WezTerm 和 iTerm2
- 所有終端機
- 只有 iTerm2
-
什麼工具用於建立代理團隊？
- spawnAgent
- spawnTeam
- createTeam
- teamUp
-
True or False： 隊友可以直接與彼此通訊。
- True
- False
-
2.1.33 修正了關於代理團隊的什麼？
- 新增 tmux 支援
- 修正 tmux 中的隊友訊息傳遞
- 新增 spawnTeam 工具
- 修正 WezTerm 渲染
-
一個團隊可以有多少隊友？
- 只有 1 個
- 最多 2 個
- 您的終端機可以顯示的數量
- 最多 4 個
答案： 1-b, 2-b, 3-True, 4-b, 5-c
總結
在本課程中，您學到了：
- 代理團隊 - 在分割窗格中運作的多個 Claude 實例
- 分割窗格終端機 - tmux、WezTerm（新增！）、iTerm2 支援
- spawnTeam - 建立和管理隊友
- 隊友通訊 - SendMessage 用於協調
- 2.1.33 修正 - 可靠的隊友訊息傳遞
下一步
在**第 19 課：分叉情境與進階技能**中，您將學到：
- 分叉子代理情境
- 技能熱重載（自動！）
- 語言設定
- 進階技能 frontmatter
進階閱讀
繼續到第 19 課：分叉情境與進階技能 →