概要
どうも、@daiki1003です！みなさん、Claude Code使ってますか？
今回はClaude Codeの実験的機能「エージェントチーム」を紹介します。複数のClaude Codeインスタンスがチームとして連携して動く機能で、一人じゃ時間がかかる調査やレビューを並列でガッとやれるようになります。
「サブエージェントと何が違うの？」って思った方、いい質問です。サブエージェントはメインに結果を返すだけの子プロセスですが、エージェントチームはメンバー同士が直接会話できるんですよね。「おい、そっちの調査結果どうだった？」みたいなやり取りが自動で行われるわけです。
それでは早速行ってみましょー！
概要図解
エージェントチームとは
エージェントチームは、1つのリーダーセッションが複数のチームメンバー（それぞれ独立したClaude Codeインスタンス）を生み出して、並列に作業させる仕組みです。
実はこれ、もともとコミュニティの中で「複数のClaude Codeセッションを手動で立ち上げて並列作業させる」というパターンが広まっていたんですよね。git worktreeで複数セッションを走らせるハックとか。それをAnthropicが公式機能として整備したのがエージェントチームです。
サブエージェントとの違いを表にまとめるとこうなります。
| サブエージェント | エージェントチーム | |
|---|---|---|
| 通信 | メインエージェントにのみ報告 | メンバー同士が直接メッセージを送り合える |
| コンテキスト | 独自のコンテキストウィンドウを持ち、結果は呼び出し元に返される | 独自のコンテキストウィンドウを持ち、完全に独立して動作する |
| 最適な用途 | 結果だけが重要な集中的タスク | 議論とコラボレーションが必要な複雑な作業 |
| 調整 | メインエージェントがすべて管理 | 共有タスクリストで自己調整 |
| トークンコスト | 低い | 高い（各メンバーが個別のインスタンス） |
要するに、結果だけ返してくれればいいならサブエージェント、メンバー同士で議論・協力させたいならエージェントチーム。この使い分けだけ覚えておけばOKです。
使うまでの手順
1. 機能を有効化する
エージェントチームはデフォルトで無効です。まず有効化が必要になります。
settings.jsonに以下を追加してください。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
settings.jsonはClaude Code内で/configコマンドを実行すると編集できます。ファイルパスは~/.claude/settings.jsonです。
2. 自然言語でチームを作る
有効化したら、あとはClaude Codeに自然言語で「チームを作って」と指示するだけです。
エージェントチームを作成して、3人のメンバーで並列にコードレビューして。 - 1人目はセキュリティ面 - 2人目はパフォーマンス面 - 3人目はテストカバレッジ
これだけで、リーダーがタスクリストを作り、メンバーをスポーンし、作業を割り振ってくれます。
3. 表示モードを選ぶ
表示モードは2種類あります。
| モード | 特徴 | 必要なもの |
|---|---|---|
| In-process | メインターミナル内で全メンバーが動く。Shift+Up/Downでメンバーを切り替え | なし（どのターミナルでもOK） |
| Split panes | 各メンバーが独自のペインを持つ。全員の出力を一度に見られる | tmuxまたはiTerm2 |
デフォルトはautoで、tmuxセッション内なら分割ペイン、そうでなければin-processになります。明示的に指定したい場合はsettings.jsonで設定できます。
{
"teammateMode": "in-process"
}
個人的にはまずin-processで試してみて、慣れてきたらtmuxの分割ペインに移行するのがおすすめです。
どういう時に使うか
エージェントチームが特に力を発揮するのは、こんな場面です。
調査・レビュー（一番おすすめ）
複数の視点から同時に調査できるのが最大の強みです。PRレビューで「セキュリティ担当」「パフォーマンス担当」「テスト担当」を同時に走らせるとか。一人でやったら30分かかるレビューが、3人並列で一気に片付きます。
競合する仮説でのデバッグ
原因不明のバグを調査するとき、1つのエージェントだと最初に見つけた仮説に引っ張られがちです。複数のメンバーにそれぞれ別の仮説を持たせて、互いに反証させると、真の原因にたどり着きやすくなります。
ユーザーからアプリが1メッセージで切断されるという報告がある。 5人のエージェントチームメイトをスポーンして、 異なる仮説を調査させて。 互いの理論に反論し合う科学的議論のように進めて。
これ面白いですよね。エージェント同士に議論させるという発想。
他にも、お互いに干渉しない別々のモジュールを並列で開発させるパターンにも向いています。
逆に向いてないケース
一方で、何でもかんでもチームにすればいいわけではありません。以下のようなケースではサブエージェントや単一セッションのほうが適しています。
- 順番に実行する必要があるタスク
- 同じファイルを編集する作業（上書き事故の原因になる）
- 依存関係が多い作業
- そもそもシンプルなタスク（調整オーバーヘッドのほうが大きくなる）
使用上の注意
トークン消費量に気をつけよう（最重要）
これは一番気をつけたいポイントです。エージェントチームは単一セッションより大幅に多くのトークンを消費します。
なぜなら、各チームメンバーがそれぞれ独立したClaude Codeインスタンスだから。3人チームを作ったら、ざっくり3倍以上のトークンが飛んでいくと思ってください。ブロードキャストメッセージ（全員に一斉送信）を使うとさらに増えます。
特にAPI課金で使っている方は、使用量をこまめにチェックしましょう。
いちいち変更許諾を聞かれるときの対処法
エージェントチームを使い始めると、チームメンバーの権限リクエストがリーダーに集まってきて、「許可しますか？」の嵐になることがあります。正直これがかなりストレスフルです。
対処法は簡単で、チームをスポーンする前に権限設定で一般的な操作を事前承認しておくことです。
/permissionsコマンドでAllowルールを追加できます。よく使うコマンドを事前に許可しておけば中断が減ります。具体的な構文は公式ドキュメントを参照してください。
あるいは、信頼できるプロジェクトでテスト目的なら--dangerously-skip-permissionsフラグで全許可することもできますが、名前の通りdangerousなので本番環境では絶対に避けましょう。リーダーがこのフラグで起動すると、全メンバーも同じ設定になります。
タスクの粒度と監視
タスクの切り方も大事です。公式ドキュメントでは、チームメンバーあたり5〜6個のタスクを作ることが推奨されています。少なすぎると手持ち無沙汰なメンバーが出るし、大きすぎるタスクだとチェックインなしで長時間走り続けてしまいます。
あと、チームを長時間放置しないこと。これ大事です。メンバーの進捗を定期的にチェックして、うまくいってないアプローチは早めに軌道修正しましょう。放置するほど、的外れな方向に進んでトークンが無駄になるリスクが高まります。
その他の注意点
- チームメンバーはリーダーの会話履歴を引き継がない。スポーン時のプロンプトに必要なコンテキストをしっかり含めましょう
- セッション再開（
/resumeや/rewind）するとin-processのチームメンバーは復元されない。再開後は新しくスポーンし直す必要があります - 1セッションにつき1チームまで。新しいチームを作る前に既存のチームをクリーンアップしてください
知っておきたい操作Tips
メンバーと直接話す
In-processモードならShift+Up/Downでメンバーを選択して、直接メッセージを送れます。「そっちの方針変えて」「もっと詳しく調べて」みたいな個別指示が出せるので覚えておくと便利です。他にもEnterでメンバーのセッション表示、Escapeで現在のターンを中断、Ctrl+Tでタスクリストの表示切り替えができます。
デリゲートモード（地味に重要）
Shift+Tabでデリゲートモードに切り替えると、リーダーが自分で作業せず調整に専念するようになります。リーダーが勝手にコード書き始めちゃうことがあるので、その対策ですね。もしデリゲートモードを使わない場合は「チームメンバーの完了を待って」と指示しましょう。
プラン承認を要求する
慎重に進めたいタスクでは、メンバーに実装前のプラン提出を要求できます。
認証モジュールをリファクタリングするチームメイトをスポーンして。 変更を加える前にプラン承認を必須にして。
リーダーがプランをレビューして、OKなら実装開始、NGならフィードバック付きで差し戻し、という流れになります。
チームの終了
作業が終わったら、必ずリーダーからクリーンアップしてください。
チームをクリーンアップして
メンバーが動いている場合は先にシャットダウンしてからクリーンアップしましょう。tmuxセッションが残ってしまった場合はtmux lsで確認して手動で終了できます。
まとめ
エージェントチームの使い所をまとめるとこうなります。
- 複数の視点が必要な調査・レビューで真価を発揮
- メンバー同士が議論・反証できるのがサブエージェントとの最大の違い
- トークン消費は大きいので、使い所を見極めよう
- 権限の事前承認で許諾ストレスを軽減
- まだ実験的機能なので、制限事項は頭に入れておこう
エージェントチーム、まだ実験的とはいえ、うまくハマるとかなり強力です。特にコードレビューや調査タスクとの相性は抜群なので、まずはそのあたりから試してみてはいかがでしょうか。参考になれば幸いです！
誰かのお役に立てば。Twitterフォローお願いします
「次回以降も記事を読んでみたい！」「この辺分からなかったから質問したい！」
そんな時は、是非Twitter (@daiki1003)やInstagram (@ashdik_flutter)のフォローお願いします♪
Twitterコミュニティ参加お願いします
Twitterコミュニティ「Flutter lovers」を開設しました！参加お待ちしております😁
☕️ Buy me a coffee
また、記事がとても役に立ったと思う人はコーヒーを奢っていただけると非常に嬉しいです！
@daiki1003
コメント