Claude Code 完全ガイド

Claude Code Agent Teams 初心者向け導入ガイド：最短で動かして安全に運用する

この記事の対象者

• Claude Code を使っている／使い始めた人
• Agent Teams をとりあえず動かしてみたい
• 最初はコードを書かせず「読むだけ」で安全に試したい

Agent Teams は複数の Claude Code セッションをチームとして調整し、メンバー同士が直接メッセージできる experimental 機能です。PRレビューを観点別に並列化したり、原因不明のバグを複数仮説で同時調査するといった使い方ができます。

experimental 機能です

Agent Teams は 2026年2月時点で experimental です。利用可否や挙動はプラン・組織設定・バージョンで変わる可能性があります。本記事の情報は執筆時点の公式ドキュメントに基づいています。

この記事のポイント

• Agent Teams を最短で有効化する手順
• 「読むだけレビュー」で安全に最初の成功体験を作る方法
• CLAUDE.md と permissions で暴走を防ぐ設定
• Subagents との使い分け基準
• 既知の制限とコスト管理のコツ

Agent Teams を使うべき条件

次の2つが揃うときに使うとコスパが良いです。

1. タスクが並列化できる（観点ごとに分割可能）
2. ワーカー同士が会話した方が速い（相互参照・反論・すり合わせ）

逆に向かないケース：

• 単独で完結する作業
• 順序依存が強い（A→B→C）
• 同じファイルを複数人が編集する（競合リスク）

最短チェックリスト

1. Claude Code をインストール
2. バージョン確認で疎通チェック
3. Agent Teams を有効化
4. 「読むだけ」3観点PRレビューを実行
5. 終わったら leader にチームをクリーンアップさせる

以降のセクションで各ステップを解説します。

課金とアカウントの前提

Claude Code は Claude.ai のサブスクリプション（Pro / Max）または Claude Console（API）での認証が必要です。

利用形態	認証方式
個人	Pro / Max プランで Claude.ai ログイン
チーム・組織	Teams / Enterprise アカウント
API直接利用	Claude Console（API課金は別体系）

Claude Code と API は課金が別

Claude.ai サブスクリプションと Claude API（Console）の課金は別物です。混同しやすいので注意してください。

インストールと疎通確認

インストール

公式のセットアップ手順に従ってください。代表的な方法：

# macOS / Linux / WSL（推奨）
curl -fsSL https://claude.ai/install.sh | bash

その他のインストール方法

• Homebrew: brew install --cask claude-code（自動更新なし）
• Windows PowerShell: irm https://claude.ai/install.ps1 | iex
• WinGet: winget install Anthropic.ClaudeCode（自動更新なし）

疎通確認

インストールできた「つもり」を潰すために、バージョン確認を実行します。

claude --version

正常にバージョンが表示されれば準備完了です。

Agent Teams を有効化する

Agent Teams は experimental のため、明示的に有効化が必要です。

方法A：環境変数（最短）

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方法B：settings.json（再現性が高い・推奨）

プロジェクトルートの .claude/settings.json に記述すると、チーム全員に同じ設定が適用されます。

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

settings.json のスコープ

• ~/.claude/settings.json — ユーザ全体に適用
• .claude/settings.json — プロジェクト単位（Git管理可能）

最初の成功体験：「読むだけ」PRレビュー

実行プロンプト

「変更しない」を明示して、まずは読むだけに寄せるのがポイントです。

PR #142 をレビューして。
観点は「セキュリティ」「パフォーマンス」「テスト」。
3人のレビュアーをスポーンして並列に見て、最後は leader が統合して要点だけ出して。
このフェーズではコード変更はしない（読むだけ）。

Claude は勝手にチームを作りません。チームの提案に対して確認してから進行します。

in-process モード操作チートシート

in-process モードでは、1つのターミナル内でチームメンバーを切り替えて操作できます。

ショートカット	操作
Shift + ↑ / ↓	チームメイトを選択・切替
Enter	選択したメイトのセッションを表示
Escape	現在のターンを中断
Ctrl + T	タスクリストの表示切替
Shift + Tab	delegate モードに切替

表示モード（teammateMode）の選択肢

settings.json で teammateMode を設定できます。

• "auto"（デフォルト）：tmux 内なら split pane、それ以外は in-process
• "in-process"：1つのターミナル内で切替
• "tmux"：tmux の split pane で並列表示

CLIフラグ --teammate-mode in-process でも指定可能です。

終了時：必ずクリーンアップ

終わったら leader に チームのクリーンアップを指示します。

チームをクリーンアップして。

クリーンアップの注意点

• 必ず leader から実行してください。メンバーからの実行はリソースが不整合になる可能性があります。
• アクティブなメンバーが残っている場合、先にシャットダウンが必要です。
• tmux セッションが残った場合は tmux ls → tmux kill-session -t <session-name> で手動削除できます。

メンバーに会話履歴は引き継がれない

Agent Teams の重要な前提：leader の会話履歴はメンバーに共有されません。

各メンバーがスポーン時に受け取るのは以下だけです：

• プロジェクトコンテキスト（CLAUDE.md、MCP サーバー、Skills）
• leader からのスポーンプロンプト

そのため、スポーン指示には対象パス・制約・Done条件まで明記してください。漠然とした指示では精度が落ちます。

CLAUDE.md の最小テンプレート

CLAUDE.md はプロジェクトのルールを Claude Code に伝えるファイルです。Agent Teams でも各メンバーが読み込みます。

初心者向け最小テンプレート（コピペ用）

# Project Rules (minimal)

## Goal
- このリポジトリでの最優先は「安全性」と「レビュー可能性」

## Do / Don't
- DO: 変更前に必ず影響範囲とDone条件を明文化する
- DO: 変更は小さく、差分は説明可能に
- DON'T: 秘密情報（.env / secrets）を読まない・出さない
- DON'T: 指示がない限り破壊的変更をしない

## How to work
- まず plan を提示して承認を取る
- "読むだけレビュー"→"小さな修正"の順で進める

## Paths
- 認証: src/auth/**
- API: src/api/**
- テスト: test/**

permissions で暴走と情報漏えいを防ぐ

Claude Code は /permissions コマンドで権限を管理できます。

ルール評価順

権限ルールは deny → ask → allow の順に評価され、最初にマッチしたルールが勝ちます。deny が常に最優先です。

初心者向けの最小設定例

「危ないものだけ deny」する設計です。

{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ]
  }
}

curl 禁止の代替：WebFetch をドメイン許可で使う

外部アクセスが必要な場合は、Bash の curl ではなく WebFetch をドメイン単位で許可する方がスコープを絞れます。

WebFetch(domain:example.com)

ワイルドカードの挙動

• * — 単一レベルにマッチ
• ** — 再帰的にマッチ
• Bash(ls *) — スペース後の * は単語境界を強制
• Bash(ls*) — スペースなしは境界を強制しない

leader を統合役に固定する：delegate mode と plan approval

delegate mode

leader が自分で作業を始めてしまう事故を防ぐモードです。delegate mode では leader は調整専用ツール（スポーン、メッセージ送信、シャットダウン、タスク管理）のみ使えます。

有効化は Shift + Tab で切り替えます。

plan approval

メンバーに実装前の計画承認を挟ませる仕組みです。

1. メンバーは読み取り専用の plan mode で作業計画を作成
2. leader に plan approval リクエストを送信
3. leader が承認 or フィードバック付きで差し戻し
4. 承認後にメンバーが実装開始

leader の承認判断はプロンプトで影響できます（例：「テストカバレッジを含む計画のみ承認して」）。

慣れるまでの推奨設定

delegate mode + plan approval をセットで使うと、leader が統合に徹し、実装ミスを事前に防げます。

既知の制限

Agent Teams は experimental です。以下の制限を把握しておいてください。

制限	詳細
/resume /rewind が復元しない	in-process のチームメンバーは復元されない。再開後に新しいメンバーをスポーンする必要がある
1セッション1チーム	新しいチームを作るには現在のチームをクリーンアップする必要がある
チームのネスト不可	メンバーが独自のチームやメンバーをスポーンすることはできない
leader は固定	チームを作成したセッションが常に leader。途中で変更や移譲はできない
split pane の対応環境	tmux または iTerm2 が必要。VS Code 内蔵ターミナル、Windows Terminal、Ghostty は未対応
スポーン時の権限	全メンバーは leader の権限モードで起動。個別設定はスポーン後に変更可能
シャットダウンの遅延	メンバーは現在のリクエストやツール呼び出しが完了してから停止する
タスク状態の遅延	メンバーがタスク完了のマークを忘れることがあり、依存タスクがブロックされる場合がある

コスト管理

Agent Teams はメンバーごとに独立したコンテキストウィンドウを持つため、人数分のトークンコストが発生します。

初心者向けの運用ルール

• メンバーは3人までから始める
• broadcast（全メンバーへの一斉送信）は控えめに — コストがチームサイズに比例する
• 「進捗報告 → 統合 → 終了」のリズムを作る
• 終了時は必ずクリーンアップして放置を防ぐ

コスパの判断基準

リサーチ、レビュー、新機能開発では追加トークンに見合う価値がある場合が多いです。ルーティン作業は単一セッションの方がコスト効率が良いです。

Subagents と Agent Teams の使い分け

観点	Subagents	Agent Teams
コンテキスト	独自のウィンドウ。結果は呼び出し元に返却	独自のウィンドウ。完全に独立
コミュニケーション	メインエージェントへの報告のみ	メンバー間で直接メッセージ可能
調整方法	メインエージェントが全体管理	共有タスクリストで自律的に調整
向いている作業	結果だけ必要な集中タスク	議論やコラボレーションが必要な作業
トークンコスト	低い（結果がメインに要約される）	高い（各メンバーが独立した Claude インスタンス）

判断基準：「ワーカー同士が会話する必要があるか？」が Yes なら Agent Teams 寄りです。

コピペ用プロンプト集

A. 「読むだけ」3観点レビュー（推奨）

PR #XXX をレビュー。
観点：セキュリティ／パフォ／テスト。3人スポーンして並列で。
各メンバーは「読むだけ」。変更提案はしてよいが、ファイルは編集しない。
最後に leader が critical / warning / info で統合して。

B. 原因不明バグの並列仮説検証

障害：APIが断続的にタイムアウト。
仮説を3つに分けて調査して：①外部API ②DBロック ③メモリリーク。
各メンバーは「証拠（ログ/該当ファイル/再現手順）」を1つ以上添えて報告。
最後に leader が最有力仮説と次アクションを1つに絞って。

C. クリーンアップ（忘れ防止）

チームをクリーンアップして、残っているメンバーセッションがない状態にして。

よくある質問

Q. Agent Teams を使うにはどのプランが必要ですか？

Claude Code が利用できるプラン（Pro / Max / Teams / Enterprise / API）であれば、experimental フラグを有効化して試せます。ただし利用可否はプランや組織設定で異なる場合があります。

Q. Subagents と同時に使えますか？

はい。Agent Teams のメンバーは通常の Claude Code セッションと同じ機能を持つため、各メンバーが内部で Subagents を使うことは可能です。ただしメンバーが独自のチームを作ることはできません（ネスト不可）。

Q. leader を途中で変更できますか？

できません。チームを作成したセッションが常に leader です。leader を変えたい場合はチームをクリーンアップして新しいチームを作り直してください。

次に読む

• Claude Code 完全ガイド
• Claude Code ベストプラクティス
• AIエージェント開発チーム構築フレームワーク

参考リンク

• Agent Teams - Claude Code Docs
• Claude Code セットアップ
• Claude Code Settings
• Permissions
• Claude Code Overview