Agent Teamsとは：セッション同士がメッセージし合う仕組み

Agent Teamsは、複数のClaude Codeセッションを「チームリード」と「チームメイト」として協調させる実験的機能です。似た機能にサブエージェントがありますが、両者は仕組みが異なります。

公式ドキュメントによれば、既定では無効化されており、settings.jsonまたは環境変数でCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定して有効化する仕組みです。

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

実際にやってみた：検証の設計

公式ドキュメントの説明を読むだけでなく、実際にheadlessモード（claude -p）でAgent Teamsを起動できるか検証しました。headlessモードの記事で扱ったこの実行方式は、cronなど無人実行の自動化と相性が良いため、Agent Teamsも同じように自動化に組み込めるかを確かめたかったからです。

用意したテスト環境

あえてバグを仕込んだ2つのPythonファイルを用意しました。

# sample_module_a.py（割引計算：上限チェック漏れのバグを仕込み）
def calculate_discount(price, is_member, coupon_code=None):
    discount = 0
    if is_member:
        discount += 0.1
    if coupon_code == "SAVE20":
        discount += 0.2
    final_price = price * (1 - discount)
    return final_price

# sample_module_b.py（逐次sleepによるパフォーマンス問題を仕込み）
def fetch_all_users(user_ids):
    results = []
    for uid in user_ids:
        results.append(fetch_user_data(uid))  # 1件ずつ2秒待つ
    return results

実行したコマンド

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude -p \
  "このディレクトリのsample_module_a.pyとsample_module_b.pyをレビューしてください。
   2人のチームメイトをエージェントチームとして起動し、1人はaのバグを、
   もう1人はbのパフォーマンス問題を、それぞれ独立にレビューさせてください。
   必ずエージェントチーム（teammates）を使い、サブエージェントではなく
   チームとして構成してください。" \
  --output-format json

ドキュメント推奨の「まずは書き込みを伴わない調査・レビュー系タスクから試す」という助言にも沿った内容です。ツール制限による偽陰性を避けるため、ツール制限をかけない条件（--permission-mode acceptEdits）でも再度実行し、2回検証しました。

結果：レビュー自体は優秀。しかし「チーム」は形成されていなかった

出てきた回答は的確だった

2回とも、次のような質の高い指摘が返ってきました。

• sample_module_a.py：割引率に上限がなく将来的に合計が100%を超えうる設計上の欠陥、入力バリデーションの欠如、クーポンコードの大文字小文字・前後空白に対する脆弱な完全一致比較、浮動小数点誤差への丸め処理の欠如
• sample_module_b.py：I/O待ちを並列化せず逐次実行しているためO(n)で処理時間が線形増加する問題、asyncioやThreadPoolExecutor導入の余地、重複ID・キャッシュの欠如

指摘の的確さだけを見れば、十分に実用的な結果です。

しかし、システム的な証拠は「チームが組まれていない」ことを示していた

問題はここからです。出力のJSONと実行環境を詳しく調べると、次の事実が分かりました。

公式ドキュメントには、チームが組まれると~/.claude/teams/{team-name}/config.jsonにチーム設定が書き出されると明記されています。しかし2回とも、このディレクトリ自体が存在しませんでした。num_turns: 1（1ターンで完結）という点も、複数の独立したセッションが並行してメッセージをやり取りする本来のAgent Teamsの動き方とは矛盾します。

興味深いのは、出力テキストの冒頭が「両チームメイトのレビューが完了しました」という書き出しだったことです。つまりClaudeは、あたかも2人のチームメイトが独立にレビューしたかのような体裁の報告文を、実際には1つのセッション・1ターンの中で生成していたことになります。中身の指摘は的確でしたが、「エージェントチームとして動いた」という指示自体は、実質的に達成されていませんでした。

何が起きていると考えられるか

公式ドキュメントを読み返すと、Agent Teamsの説明は一貫して対話型のターミナル操作を前提にしています。

• チームメイトは画面下の「エージェントパネル」に表示され、矢印キーで選択する
• 特定のチームメイトに直接メッセージを送るには、パネルで選択してEnterを押す
• 分割ペイン表示にはtmuxやiTerm2が必要

これらはいずれも、人間がターミナルの前で対話的に操作する状況を前提にした設計です。claude -pによるheadlessモードは、そもそも1回限りの指示を投げて結果を受け取るだけの実行形態のため、チームメイトの立ち上げ・パネル管理・チーム間メッセージングという仕組み自体が動く前提を欠いている可能性が高いと考えられます。エラーで落ちるのではなく、リクエスト自体は普通に処理され、あたかもチームが動いたかのような文章が生成される、という「静かなフォールバック」になっている点が、実際に試してみないと分からなかったポイントです。

実務上の結論：headless・自動化用途では現時点でサブエージェントを使う

よくある質問

まとめ

Agent Teamsは魅力的な機能ですが、今回の検証が示す通り、ドキュメントの説明だけでは分からない挙動があります。自動化パイプラインに組み込む前に、まずは小さなタスクで実際に試し、~/.claude/teams/ディレクトリが作られているかを確認してみることをおすすめします。