🤖

Claude Codeマルチエージェント実践記 - 10体→5体へ、そして公式Swarmへ

Claude CodeのTask機能に物足りなさを感じ、tmux+Markdownベースの自作マルチエージェントシステムを構築。10体→5体への最適化、コスト管理、そして公式Claude Swarmとの比較まで、実践経験に基づくガイド。

AIClaude Codeマルチエージェント開発効率化

Claude Codeマルチエージェント実践記 - 10体→5体へ、そして公式Swarmへ

Claude Codeで複数のAIエージェントを同時に動かし、タスクを並列処理する。

聞くだけなら簡単そうですが、実際にやってみると設計・コスト・通信方式のすべてで壁にぶつかります。この記事では、Task機能の限界を感じてから、10体構成の将軍システム導入、5体構成の自作システムへの最適化、そして公式Agent Teams（通称Swarm）の発見まで、実際に手を動かして得た知見を共有します。

🤔 はじめに - Claude Code Task機能の限界

Claude Codeには標準でサブエージェント（Task機能）が搭載されています。Explore、Plan、general-purposeといった特化型エージェントが、メインセッション内でタスクを処理してくれる機能です。

便利な機能ですが、実際に使い込むと以下の点が気になりました。

  • 🎯 精度にムラがある: 複雑なタスクを渡すと、期待と違う結果が返ってくることがある
  • 👀 裏で何が起きているか見えない: サブエージェントが今どこまで進んでいるのか、何をしているのかが不透明
  • 🔒 メインセッションに結果が返るだけ: サブエージェント同士が直接やり取りすることはできない

特に「可視性の低さ」は大きな不満でした。tmuxで全エージェントの動きをリアルタイムに見たい。もっと制御したい。そう思い始めたのが、マルチエージェント構築のきっかけです。

サブエージェントの詳細は公式ドキュメントを参照してください。

📐 マルチエージェントの基本概念

マルチエージェントシステムとは、複数のAIエージェントが協調してタスクを実行する仕組みです。

人間の組織構造に例えると分かりやすくなります。

パターン 説明 例
逐次実行 1体ずつ順番に処理 1人の社員がタスクを順番にこなす
並列実行 複数体が同時に処理 チームメンバーが手分けして作業
階層型 指揮官がタスクを分解し、ワーカーに委任 マネージャーが部下に仕事を振る

Claude CodeのTask機能は逐次実行に近い構造です。メインエージェントがサブエージェントに委譲し、結果を受け取る。一方、自作マルチエージェントでは階層型の並列実行を目指しました。

⚔️ 第1世代: multi-agent-shogun（将軍システム）

概要

Zennの記事をきっかけに、multi-agent-shogunを導入しました。tmuxベースのマルチエージェントシステムで、戦国時代をモチーフにした3階層構成です。

役割 人数 モデル 担当
将軍（Shogun） 1 Opus プロジェクト統括
家老（Karo） 1 Opus タスク管理・足軽への指示
足軽（Ashigaru） 8 Sonnet/Opus 実作業

合計10体。tmux上で全エージェントがリアルに動いているのが見えます。

【shogunセッション】将軍の本陣
┌─────────────────────────────┐
│  Pane 0: 将軍 (SHOGUN)      │  ← 総大将・プロジェクト統括
└─────────────────────────────┘

【multiagentセッション】家老・足軽の陣（3x3 = 9ペイン）
┌─────────┬─────────┬─────────┐
│  karo   │ashigaru3│ashigaru6│
│  (家老) │ (足軽3) │ (足軽6) │
├─────────┼─────────┼─────────┤
│ashigaru1│ashigaru4│ashigaru7│
│ (足軽1) │ (足軽4) │ (足軽7) │
├─────────┼─────────┼─────────┤
│ashigaru2│ashigaru5│ashigaru8│
│ (足軽2) │ (足軽5) │ (足軽8) │
└─────────┴─────────┴─────────┘

起動スクリプト（shutsujin_departure.sh）を実行すると、この全体がtmux上に展開されます。

✅ 良かった点

  • tmuxで全エージェントがリアルタイムに見える: Task機能の不透明さが一発で解消
  • YAML + send-keysのシンプルな通信: 追加のAPIやサーバーは不要
  • Battle Formations（陣形）: Sonnet/Opusの配分を切り替えられる柔軟性

⚠️ 課題

しかし、使い込むうちにいくつかの問題が見えてきました。

  • 🧠 10体は多すぎる: 認知負荷が高く、全体を把握しづらい
  • 📢 3階層は冗長: 将軍→家老→足軽の伝言ゲームで、2階層で十分だった
  • 💸 コスト問題: Claude Code Maxの$100プランだと、10体同時稼働は一瞬で使い切る。$200プランが前提の設計
  • 😴 実働率の低さ: 足軽8人中、実際に同時に動いているのは半分程度

特にコストは切実な問題でした。$100プランで運用するには、エージェント数を絞る必要があります。

🍄 第2世代: kinoko（菌糸ネットワーク型）

🔧 設計変更の理由

将軍システムの課題を踏まえ、以下の方針で再設計しました。

変更点 将軍システム kinoko
エージェント数 10体 5体
階層 3（将軍→家老→足軽） 2（指揮官→ワーカー）
ワーカー数 8人 4人
通信形式 YAML Markdown
コスト感 $200プラン推奨 $100プランでギリギリ運用可能

半減させただけではなく、YAML→Markdownへの変更でClaude自体が得意な形式に合わせています。

🏗️ アーキテクチャ

菌糸ネットワークをモデルにした2層構成です。「菌類」の命名はテーマ的なもので、技術的な意味はありません。

        ユーザー
          │
          ▼ (send-keys)
    ┌──────────┐
    │  霊芝    │  指揮官 (Opus)
    │ (reishi) │  タスク分解・進捗管理・ダッシュボード更新
    └────┬─────┘
         │ queue/tasks/{worker}.md + send-keys
         ▼
    ┌──────────┬──────────┐
    │ beni (0) │ cord (2) │  ワーカー上段
    ├──────────┼──────────┤
    │ mata (1) │ enok (3) │  ワーカー下段
    └──────────┴──────────┘
役割 名前 モデル 性格
指揮官 霊芝 (reishi) Opus 賢者。タスク分解・進捗管理
ワーカー1 ベニテングタケ (beni) Opus 創造的で大胆な実装
ワーカー2 冬虫夏草 (cordyceps) Opus 容赦なく侵食する実行力
ワーカー3 マタンゴ (matango) Sonnet 増殖するように反復処理
ワーカー4 エノキ (enoki) Sonnet 軽量タスクを素早くこなす

Opus 3体 + Sonnet 2体の構成で、重い作業はOpusに、軽いタスクはSonnetに振り分けています。

kinoko起動画面——deploy.shの菌糸ネットワーク図

📡 通信プロトコル

通信はすべてファイル書き込み + tmux send-keysで行います。追加のAPIサーバーやデータベースは不要です。

ユーザー → 霊芝（send-keysで直接指示）
  ↓ タスク分解
霊芝 → queue/tasks/{worker}.md に書き込み + send-keysで起こす
  ↓ 実行
ワーカー → queue/reports/{worker}.md に書き込み + send-keysで報告
  ↓ 集約
霊芝 → dashboard.md 更新

タスクファイルの例

霊芝がワーカーに渡すタスクファイル（queue/tasks/beni.md）:

# タスク

- **タスクID**: task_001
- **元コマンド**: cmd_001
- **プロジェクト**: kinoko
- **対象パス**: /path/to/target
- **状態**: assigned

## 内容

deploy.shにANSIカラー0の再定義を追加する。
ダークモードで黒文字が見えない問題を修正すること。

## 備考

tmux 3.4+のpane-colours[0]オプションを使用する。

報告ファイルの例

ワーカーが返す報告（queue/reports/beni.md）:

# 報告

- **ワーカー**: beni
- **タスクID**: task_001
- **状態**: done

## 結果

pane-colours[0]でANSI color 0をcolour240に再定義。
全5ペインに適用完了。ダークモードでの黒文字が視認可能に。

## 変更ファイル

- deploy.sh（ペインカラー設定追加）

🏷️ ペイン識別の工夫 - @agent_id

tmuxのペインインデックスは位置ベースで再割り当てされるため、分割後にインデックスがずれる問題がありました。これを解決するために、各ペインにカスタム属性@agent_idを設定しています。

# deploy.sh での設定
tmux set-option -p -t "$PANE_BENI" @agent_id "beni"
tmux set-option -p -t "$PANE_CORD" @agent_id "cordyceps"
tmux set-option -p -t "$PANE_MATA" @agent_id "matango"
tmux set-option -p -t "$PANE_ENOK" @agent_id "enoki"
tmux set-option -p -t "$PANE_REISHI" @agent_id "reishi"

send-keysでメッセージを送る際は、この@agent_idでペインを特定します。

# @agent_idからペインIDを取得する関数
get_pane() {
  tmux list-panes -t kinoko:0 -F '#{pane_id} #{@agent_id}' \
    | grep " $1$" | cut -d' ' -f1
}

# 使用例: マタンゴにタスク確認を依頼
PANE=$(get_pane matango)
tmux send-keys -t "$PANE" 'タスクを確認してください'
tmux send-keys -t "$PANE" Enter

send-keysは必ず2回に分けます。テキストとEnterを1回で送ると、Enterが権限プロンプトに吸われる場合があるためです。

🚀 起動シーケンス

deploy.shで5体が一括起動します。

#!/usr/bin/env bash
# kinoko 起動スクリプト（抜粋）

SESSION="kinoko"

# ペインIDを取得するヘルパー
get_newest_pane_id() {
    tmux list-panes -t "$SESSION" -F '#{pane_id}' \
      | sort -t '%' -k2 -n | tail -1
}

# セッション作成（Pane 0: ベニテングタケ）
tmux new-session -d -s "$SESSION" -c "$KINOKO_DIR" -x 220 -y 65
PANE_BENI=$(get_newest_pane_id)

# 冬虫夏草（ベニの右に分割）
tmux split-window -h -t "$PANE_BENI" -c "$KINOKO_DIR"
PANE_CORD=$(get_newest_pane_id)

# マタンゴ（ベニの下に分割）
tmux split-window -v -t "$PANE_BENI" -c "$KINOKO_DIR"
PANE_MATA=$(get_newest_pane_id)

# エノキ（冬虫夏草の下に分割）
tmux split-window -v -t "$PANE_CORD" -c "$KINOKO_DIR"
PANE_ENOK=$(get_newest_pane_id)

# 霊芝（下部全幅で分割、高さ40%）
tmux split-window -v -f -t "$PANE_BENI" -c "$KINOKO_DIR" -p 40
PANE_REISHI=$(get_newest_pane_id)

ペイン分割時にインデックスではなくペインID（%0, %1等の不変ID）で追跡しているのがポイントです。tmuxのペインインデックスは分割のたびに位置ベースで振り直されるため、インデックス指定だとレイアウトが崩壊します。

💻 実際の運用

起動後のレイアウトは以下のようになります。

┌──────────┬──────────┐
│ beni     │cordyceps │  ワーカー上段（Opus × 2）
├──────────┼──────────┤
│ matango  │ enoki    │  ワーカー下段（Sonnet × 2）
├──────────┴──────────┤
│      reishi         │  指揮官（全幅・40%高）
└─────────────────────┘

霊芝ペインにユーザーが指示を送ると、霊芝がタスクを分解し、各ワーカーのタスクファイルに書き込んでsend-keysで起こす。ワーカーは作業完了後、報告ファイルに結果を書いて霊芝にsend-keysで通知。霊芝がdashboard.mdを更新して全体の進捗を可視化する、というサイクルです。

tmuxの全ペインでClaude Codeがリアルタイムに動いている様子が見えるため、「今何が起きているか」が常に把握できます。

kinoko稼働中——5ペインで全エージェントがリアルタイムに動いている

⚡ 公式ソリューション: Agent Teams（通称Swarm）

🔍 発見の経緯

kinokoを運用していたある日、Claude Code側から「マルチエージェントを起動しますか？」と提案されました。

Agent Teamsという機能が、実験的に実装されていたのです。環境変数1つで有効化できます。

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

先に自作してしまった形ですが、公式がどのような設計にしたのかを知ることで、自作システムの設計判断を振り返る良い機会になりました。

✨ 特徴

Agent Teams公式ドキュメントによると、主な特徴は以下の通りです。

  • リーダー + チームメンバー構成: 自作の「指揮官 + ワーカー」と同じ発想
  • 共有タスクリスト: 自作のdashboard.mdに相当
  • エージェント間の直接メッセージング: 自作のsend-keysに相当
  • tmux分割ペインモードもサポート: in-processモード（メインターミナル内）とsplit-paneモード（tmux/iTerm2）を選べる
  • デリゲートモード: リーダーを調整のみに制限し、自ら作業しないようにできる

🔄 Sub-agents（Task機能）との違い

公式ドキュメントでも、Sub-agents（従来のTask機能）とAgent Teamsの違いが明確に整理されています。

項目 Sub-agents Agent Teams
コンテキスト 独自ウィンドウ。結果は呼び出し元に返却 独自ウィンドウ。完全に独立
通信 メインエージェントにのみ報告 メンバー同士が直接メッセージ
調整 メインエージェントが全管理 共有タスクリストで自己調整
最適な用途 結果のみ必要な焦点タスク 議論・協力が必要な複雑タスク
トークンコスト 低い 高い（各メンバーが個別インスタンス）

📊 自作システムとの比較

Task機能、将軍システム、kinoko、Agent Teamsを並べてみます。

項目 Task機能 shogun ⚔️ kinoko 🍄 Agent Teams ⚡
エージェント数 可変 10体 💪 5体 可変
階層 フラット 3階層 2階層 リーダー+メンバー
通信 結果返却のみ YAML+send-keys Markdown+send-keys TeammateTool
可視性 🙈 ほぼ見えない 👁️ tmuxで丸見え 👁️ tmuxで丸見え in-process or tmux
コスト 💰 💰💰💰💰💰 💰💰 💰💰💰
対応プラン どれでも $200推奨 $100でギリギリ 不明
大規模対応 ⭐ ⭐⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐⭐
セットアップ なし ✨ 🔧🔧🔧 🔧🔧 なし ✨

将軍システムは8ワーカー3階層で大規模プロジェクト向き、kinokoは4ワーカー2階層で個人開発向きと、用途が異なります。

Agent Teamsはまだ実験的機能で、セッション再開不可・1チームのみ等の制限があります。本格的に使いこなすのはこれからです。

🎓 自作して良かったこと

Agent Teamsの存在を知った今、「先に作ってしまったのは無駄だったか？」と問われれば、答えは明確にNoです。

  • 📡 通信設計の理解: ファイルベース通信、send-keysのタイミング制御、ペイン識別の問題など、自分で設計したからこそ身についた知識
  • 💰 コスト感覚: 10体→5体への最適化を通じて、「何体が適正か」「どこにOpusを使いどこにSonnetを使うか」の勘所が分かった
  • 🔍 公式の設計意図が読める: Agent Teamsの「共有タスクリスト」「リーダー制約（デリゲートモード）」「tmuxサポート」といった設計判断が、自分の経験と照らし合わせて「なるほど」と理解できる

先に自分で作った経験があるからこそ、公式ツールをより深く理解し、適切に使い分けられるようになります。

🎸 まとめ

マルチエージェントの導入は、コスト・設計・運用のすべてで判断が求められます。手軽さを求めるならTask機能、可視性と学びを重視するなら自作、安定した基盤が必要ならAgent Teamsと、用途に応じた選択肢があります。

現在もkinokoで運用を続けています。公式Agent Teamsのほうが安定しているのは分かっていますが、tmuxで5体が同時に動いている画面を見ながら開発する体験は、APIを叩くだけでは得られないものがあります。

自分で通信設計を書き、ペイン管理の罠にはまり、コスト最適化で10体を5体に削った経験があるからこそ、公式ツールの設計意図が読めるようになりました。遠回りに見えますが、先に自作してから公式に移行するルートは、確実に理解の深さが違います。

📎 関連記事

💬 生成AI導入のご相談

この記事で紹介したような業務自動化やAI活用に興味がある方は、お気軽にご相談ください。

  • GitHub Actionsを使った自動化
  • Claude Code / ChatGPTの業務活用
  • 週報・月報の自動生成システム

中小企業・スタートアップ向けに、エンジニアが直接サポートいたします。

👉 サービス詳細を見る | LINEで相談する

💬 生成AI・DX導入のご相談

この記事に関するご質問や、生成AI導入についてお気軽にご相談ください

LINEで相談する

© 2022-2025 infoHiroki. All rights reserved.