Claude Code Agent Teams: 既存のスキル・エージェントのナレッジ活用法

TL;DR

• Agent Teamsは複数のClaude Codeインスタンスをチームとして協調動作させる仕組み。従来のサブエージェント（Task tool）とはアーキテクチャが異なる
• 既存のスキルやエージェント定義のナレッジをAgent Teamsで活用するには、プロンプト内でファイルパスを明示的に指定して読み込ませる必要がある（構造的な指定方法は未提供）
• トークン消費はスキル方式の数倍。スキル方式で十分な作業はスキルで、並列実行の価値が明確な場合にAgent Teamsを試すのが現実的

Agent Teamsの概要

2026年2月5日、Claude Opus 4.6と同時に公開された実験的プレビュー機能です。複数のClaude Codeインスタンスが「チーム」として並列で動きます。

Claude Codeの拡張機構にはいくつかのレイヤーがあります。

スキル（Skill tool）
  └── メインセッション内で展開・実行
       └── 内部でTask toolを使うこともある

サブエージェント（Task tool）
  └── 独立インスタンスとして起動
  └── subagent_type でカスタムエージェント定義を指定可能

Agent Teams（TeamCreate + SendMessage + TaskList等）
  └── チームメイト起動 = Task tool + チーム間通信・タスク共有

従来のサブエージェントはTask toolで起動される独立インスタンスで、親→子のハブ&スポーク型です。子同士は会話できず、結果を親に返すだけ。Task toolにはビルトインで Bash / general-purpose / Explore / Plan の4タイプがあり、さらに subagent_type でカスタムエージェント定義（.claude/agents/*.md）を指定すると、定義に書かれたナレッジが自動的に読み込まれます。

Agent TeamsはこのTask toolの上にチーム間通信やタスク共有の仕組みを追加したオーケストレーション層です。チームメイト同士が直接メッセージを送り合えるのが大きな違いです。

【サブエージェント方式】
  親エージェント
    ├── Task → 子A（結果を親に返却）
    ├── Task → 子B（結果を親に返却）
    └── Task → 子C（結果を親に返却）
  ※ 子同士は会話できない。subagent_typeで定義を指定可能

【Agent Teams方式】
  Team Lead
    ├── Teammate A ←→ Teammate B
    ├── Teammate B ←→ Teammate C
    └── Teammate A ←→ Teammate C
  ※ チームメイト同士がメッセージを送り合える

なお、チームメイトも独立したClaude Codeインスタンスなので、仕組み上はTask toolでサブエージェントを呼び出せるはずです（公式の制限は「ネストチーム不可」であり、Task tool単体の利用は制限されていません）。しかし実際に試したところうまく動作しませんでした。これができれば既存のカスタムエージェント定義をそのまま活用できるので、今後の改善に期待したいところです。

以下は7人のレビュアーがtmux split panesで並列動作している様子です。

チーム全体で共有するタスクリストがあり、タスクの状態管理や依存関係の定義ができます。ブロックが解消されると空いたチームメイトが次のタスクを自律的にクレームする仕組みです。ただしファイルレベルのロック機構はないので、同じファイルへの同時書き込みには注意が必要です。

有効化と使い方

settings.jsonで有効化します。

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "auto"
}

teammateMode の "auto" はtmux内ならsplit panes、それ以外ではin-process（Shift+Up/Downで切替）を自動選択します。使い方は自然言語で指示するだけです。

このプロジェクトのPR #42をレビューするチームを作って。
3人のレビュアーをスポーンして:
- セキュリティ担当
- パフォーマンス担当
- テストカバレッジ担当
それぞれレビューして結果を報告させて。

前提として、Max 5x ($100/月) 以上のプランを推奨します。Proプラン ($20/月) では制限に達しやすいです。

既存ナレッジの活用: 自然言語プロンプトの現状

Agent Teamsを使ううえで知っておくべき点があります。

Claude Codeにはスキル（SKILL.md）やカスタムエージェント（.claude/agents/*.md）といった既存の拡張機構があります。単体セッションでは自動的に読み込まれますし、Task toolのサブエージェントでも subagent_type で名前を指定するだけで使えます。

ところが、Agent Teamsではチームメイトに「このスキルを使え」「このエージェント定義で動け」といった構造的な指定方法が現時点では提供されていません。チームメイトに既存の定義ファイルを活用させたい場合、プロンプト内でファイルパスを書いて「このファイルを読め」と自然言語で指示する形になります。

パスを細かく指定するしかない

たとえば、コードレビュー用のエージェント定義を ~/.claude/agents/ に用意しているとします。Agent Teamsでこれを活用するには、ディレクトリ構造とファイルパスをプロンプトに書き出して、各チームメイトに「どのファイルを読み、どう使うか」を伝える必要があります。

### ディレクトリ構造

~/.claude/
├── agents/                       # レビュー観点の定義
│   ├── review-architecture.md
│   ├── review-naming.md
│   └── review-frontend.md
└── knowledge/                    # 参考ナレッジ
    ├── architecture/
    │   ├── patterns.md
    │   └── anti-patterns.md
    └── naming/
        └── conventions.md

### チームメイトの読み込み手順

1. `~/.claude/agents/review-{自分の担当}.md` を読み、
   レビュー観点・出力形式を把握する
2. 定義内に参照ファイルがあれば、対応するナレッジを読み込む
3. ナレッジの内容をレビューの根拠として活用する

スキル方式やTask tool方式なら、エージェント定義のパスや読み込み順は仕組み側が処理してくれます。Agent Teamsではプロンプトの中で自分で書くしかないのが現状です。

スキル方式との比較

つまり、スキルやエージェント定義として蓄積してきたナレッジがあっても、Agent Teamsで活用するにはその内容を自然言語プロンプトに変換する作業が必要です。将来的にAgent Teamsからスキルやエージェント定義を直接参照できるようになれば解消されるはずですが、2026年2月時点ではまだその段階にありません。

プロンプト設計のポイント

Agent Teamsの公式ドキュメントとコミュニティの知見から、押さえておくべきポイントをまとめます。

チームメイトへのコンテキスト共有

チームメイトはリーダーの会話履歴を引き継がず、独立したインスタンスとして起動します。CLAUDE.mdやMCPサーバーは自動で読み込まれますが、それ以外の情報はスポーン時のプロンプトに含めるか、ファイル経由で渡す必要があります。

出力ファイルの分離

ファイルレベルのロック機構がないので、各チームメイトが異なるファイルセットを担当するように設計してください。

Phase構造による段階制御

プロンプトをPhaseに分けて「準備 → 並列実行 → 統合 → 完了」の流れを明示すると、Team Leadの動きを制御しやすくなります。

Delegate Mode（Shift+Tab） も有効です。リーダーのツール実行権限を制限して、コーディネーションに専念させるモードですが、2026年2月時点でチームメイトがツールアクセスを失うバグが報告されています（GitHub Issue #24073）。

サンプル: Agent Teamsでコードレビューするプロンプト

上記のポイントを反映した、Agent Teams版コードレビュープロンプトのサンプルです。既存のエージェント定義ファイルをチームメイトに読み込ませる構成例になっています。

前提: ~/.claude/agents/ にエージェント定義ファイルを配置していることを想定しています。定義ファイルがなくてもチームは起動しますが、レビューの観点や出力形式は定義の内容に依存します。

# Architecture Reviewer

## 役割
アーキテクチャ・設計レベルのコードレビューを行う。

## レビュー観点
- ディレクトリ構造とレイヤー分離の妥当性
- 依存関係の方向
- 単一責任の原則の遵守
- 過度な抽象化や不要な複雑性

## スコアリング
各指摘に重要度タグを付与:
- [Critical]: 重大な問題
- [Warning]: 改善が望ましい懸念
- [Suggestion]: より良い設計への提案

## 出力形式
- **[重要度]** ファイル名:行番号 - 指摘内容
  - 理由: なぜ問題か
  - 改善案: どう修正すべきか

# Naming Reviewer

## 役割
変数・関数・クラス・ファイル名の命名規約をレビューする。

## レビュー観点
- 言語別の命名規約（camelCase / snake_case / PascalCase）の遵守
- 名前から役割が推測できるか（意味の明確さ）
- 略語の一貫性（例: btn vs button の混在）
- Boolean変数のプレフィックス（is / has / should）

# Frontend Reviewer

## 役割
React/Vue等のフロントエンド固有パターンをレビューする。

## レビュー観点
- コンポーネント分割の粒度とProps設計
- 状態管理パターンの適切性
- パフォーマンス（不要な再レンダリング、メモ化の過不足）
- アクセシビリティ（セマンティックHTML、ARIA属性）

プロンプト全文

このリポジトリでエージェントチームを使ってコードレビューを実行してください。
手順に従い、自律的に進めてください。判断に迷う場合のみユーザーに確認してください。

## 参照ファイルガイド

レビューに必要な定義ファイルとナレッジが `~/.claude/` 配下にあります。
各チームメイトは自分の担当に対応するファイルを読み込んで活用してください。

### ディレクトリ構造

~/.claude/
├── agents/                       # レビュー観点の定義（観点・出力形式）
│   ├── review-architecture.md    # アーキテクチャレビュー
│   ├── review-naming.md          # 命名規約レビュー
│   └── review-frontend.md        # フロントエンド固有（条件付き）
│
└── knowledge/                    # 参考ナレッジ
    ├── architecture/
    │   ├── patterns.md
    │   └── anti-patterns.md
    ├── naming/
    │   └── conventions.md
    └── frontend/
        └── best-practices.md

### チームメイトの読み込み手順

1. `~/.claude/agents/review-{自分の担当}.md` を読み、
   レビュー観点・出力形式を把握する
2. 定義内に参照ファイルがあれば、
   `~/.claude/knowledge/` から対応するファイルを読み込む
3. ナレッジの内容をレビューの根拠として活用する

---

## 手順

### Phase 0: レビュー対象の確認

ユーザーに以下を確認してください:

1. **レビュー対象**: 特定ファイル / 直近コミット / プロジェクト全体
2. **レビュー深度**: フル（デフォルト） / クイック（Criticalのみ）

### Phase 1: 準備（Team Lead が実行）

1. スクラッチディレクトリを作成:
   `.claude/code-review-team/.scratch/{YYYY-MM-DD-HHmm}/`

2. 「直近コミット」が選ばれた場合のみ差分コンテキストを生成:
   - `git diff HEAD~N` の結果を `{スクラッチ}/diff-context.md` に保存

3. テックスタック検出を実行:
   `package.json`、`requirements.txt` 等からフレームワークを特定し、
   結果を `{スクラッチ}/stack-detection.md` に出力

4. 検出結果を読み、Phase 2 のチーム構成を決定

### Phase 2: チーム作成 & 並列レビュー

チーム名 "code-review" でチームを作成し、
以下のチームメイトを並列でスポーンしてください。

#### 必須メンバー（常に起動）

1. **architecture-reviewer**
   - 役割: アーキテクチャ・設計レベルのレビュー
   - 定義: `~/.claude/agents/review-architecture.md`
   - 出力先: `{スクラッチ}/architecture-review.md`

2. **naming-reviewer**
   - 役割: 命名規約のレビュー
   - 定義: `~/.claude/agents/review-naming.md`
   - 出力先: `{スクラッチ}/naming-review.md`

#### 条件付きメンバー（スタック検出結果に基づき追加）

- **frontend-reviewer** — React/Vue等の検出時
  定義: `~/.claude/agents/review-frontend.md`
  出力先: `{スクラッチ}/frontend-review.md`

#### 全チームメイト共通ルール

- まず `{スクラッチ}/stack-detection.md` を読み込むこと
- 自分のエージェント定義を読み、観点・出力形式に従うこと
- 定義内に参照ファイルがあれば `~/.claude/knowledge/` から読み込むこと
- レビュー結果はインクリメンタルに出力先ファイルに書き込むこと
- 各指摘に重要度タグを付与: [Critical] / [Warning] / [Suggestion]
- 完了したら Team Lead にメッセージで報告:
  「レビュー完了。Critical: X件, Warning: Y件。詳細は {出力先} を参照」

### Phase 3: レポート統合

全チームメイトの完了を確認したら:

1. `{スクラッチ}/` 配下の全レビューファイルを読み込み、
   重複を排除し優先度を統一して統合レポートを生成
   **注意**: 統合対象は今回のスクラッチ内のファイルのみ
2. 出力先: `docs/code-review-team/{YYYY-MM-DD-HHmm}-review.md`

### Phase 4: 完了

1. チーム "code-review" を削除
2. レポートをユーザーに提示し、修正方針を確認:
   - 全指摘を一括修正
   - Critical/Warning のみ修正
   - 修正は自分で行う（レポートのみ）

このサンプルのポイントは、プロンプト冒頭にディレクトリ構造を記載し、各チームメイトに読み込むべきファイルのパスを明示している点です。スキル方式なら不要な記述ですが、Agent Teamsでは現状これが必要です。

トークン消費について

Agent Teamsのトークン消費はかなり大きいです。各チームメイトが独立したClaude Codeインスタンスとして動作するので、チーム人数に比例してコストが増えます。

Max 20x（$200/月）プランで、5人以上のチームメイトを含むチームを1時間に2-3回実行した場合、Max使用量の約4%を消費しました。各チームメイトが独立したインスタンスなので、人数が増えるほどコストは膨らみます。

正直なところ、スキル方式（Task tool）とAgent Teamsで最終的なアウトプットの品質にどれだけ差が出るかは、数回使った程度では測りきれていません。並列実行による速度面の利点は体感できますが、その差に見合う品質向上が得られるかは継続的な検証が必要です。

チームメイトにSonnetを指定すればコストは抑えられますが、Proプラン ($20/月) では現実的に厳しく、Max ($100-200/月) が最低ラインだと思います。

週次リセットの活用

Claude Codeの使用量制限は7日間のローリングウィンドウでリセットされます。/usage コマンドで次のリセットタイミングを確認できるので、余裕がある時期にAgent Teamsを試すと計画的に組み込みやすくなります。

制限事項（2026年2月時点）

Agent Teamsは実験的プレビュー段階です。主な制限をまとめておきます。

まとめ

Agent Teamsは、チームメイト間の直接通信と共有タスクリストによる自律的な連携を実現する仕組みです。

ただ、現時点ではチーム構成のすべてを自然言語プロンプトで記述する必要があり、既存のスキルやエージェント定義を活用するにはファイルパスを細かく指定するしかありません。スキル方式なら仕組み側がやってくれていたことを、プロンプトの中で自分で書くことになります。

トークン消費も大きく、スキル方式との明確な効果の差はまだ十分に検証できていません。今後スキルやエージェント定義との統合が進むことに期待しつつ、現時点では「スキル方式で十分な作業はスキルで、並列実行の価値が明確な場合にAgent Teamsを試す」という使い分けが現実的だと思います。

参考

• Orchestrate teams of Claude Code sessions - Claude Code公式ドキュメント
• Introducing Claude Opus 4.6 - Anthropic

ZSL

AIエンジニア

生成AIを活用した開発ワークフローの研究・実践をしています。