マルチエージェントAI開発の現実 — tmux手動オーケストレーションから自律実行フローへの移行記
はじめに
「AIエージェントを複数並列で動かせば開発が爆速になるのでは」と考えて、マルチエージェントオーケストレーションシステム multi-agent-shogun を導入しました。
tmux上で複数のClaude Codeインスタンスを戦国時代の軍制で管理するという、ユニークなOSSです。forkして自分の環境に合わせた設定を入れ、さあ本格運用——と思った矢先、Claude Code本体にオーケストレーション機能が追加されました。
結果、導入から2週間で別の方式に移行しました。移行先は、Claude Codeの組み込みオーケストレーション機能と、OpenClaw（AIエージェント管理ツール）のセッション管理を組み合わせた自律実行フローです。この短い期間の比較で見えてきたものがあったので共有します。
比較対象
A. multi-agent-shogun（tmux + YAMLキュー方式）
yohey-w氏が開発したOSSで、tmux上で複数のClaude Codeインスタンスを戦国時代の軍制で管理します。
殿（人間）
│
▼
┌──────────────┐
│ 将軍(SHOGUN) │ ← Claude Code #1: 統括・戦略
└──────┬───────┘
│ YAMLファイル + tmux send-keys
┌──────▼───────┐
│ 家老(KARO) │ ← Claude Code #2: タスク分解・管理
└──────┬───────┘
│
┌─┬─┬─┬─┴─┬─┬─┬─┐
│1│2│3│4│5│6│7│8│ ← Claude Code #3〜10: 実行部隊
└─┴─┴─┴─┴─┴─┴─┴─┘
足軽(ASHIGARU)
起動はbashスクリプトでtmuxセッション作成 → 9ペイン展開 → 全インスタンスにClaude Code起動 → 各自の指示書を読み込ませる、という流れです。
B. 現行フロー（Claude Code + OpenClaw方式）
3つのツールを組み合わせた方式です。
- Claude Code（agent teams）: Claude Code本体に組み込まれたオーケストレーション機能。タスク分解とサブエージェントの自動起動を担う
-
OpenClaw: AIエージェントのセッション管理ツール。heartbeat（定期巡回）、cron（スケジュール実行）、
sessions_spawn（隔離セッションでのタスク実行）を提供 - 自律実行フロー: 上記2つを組み合わせた運用ルール。司令塔AI（OpenClawメインセッション）が判断し、Claude Codeやsessions_spawnに実行を委譲する
殿（人間）
│
▼
┌──────────────┐
│ 司令塔AI │ ← OpenClawメインセッション（判断・委譲）
└──────┬───────┘
│
┌─────┼──────────┐
▼ ▼ ▼
[spawn] [spawn] [Claude Code]
(調査) (分析) (agent teams で並列実装)
↓ ↓ ↓
完了→報告 完了→報告 完了→報告
shogunとの最大の違いは、エージェントが常駐せず必要時のみ起動する点です。
multi-agent-shogunの設計から読み取れる知見
shogunの設計には、マルチエージェント開発で直面する問題への対処が随所に埋め込まれています。運用してみて、その意図が理解できた部分を紹介します。
1. tmux send-keysの罠
shogunの指示書で最も強調されていたのが、エージェント間通信の制約です。
# ❌ これが動かない
tmux send-keys -t multiagent:0.0 'タスクを実行せよ' Enter
# ✅ 2回に分けないとEnterが正しく解釈されない
tmux send-keys -t multiagent:0.0 'タスクを実行せよ'
tmux send-keys -t multiagent:0.0 Enter
たった1行のコマンドが動きません。tmuxのキー送信タイミングとClaude Codeの入力バッファの相性問題です。shogunの指示書には「絶対禁止パターン」「2回に分けろ」と明記されており、この制約を発見した開発者の苦労が伺えます。
OpenClawのsessions_spawnやClaude Codeのagent teamsはAPI経由で通信するため、この問題は存在しません。
2. 「待機できない」問題
Claude Codeは対話型AIです。プロンプトが表示されている状態は「待機中」ではなく「停止中」です。
❌ 家老が足軽にタスクを振って「報告を待つ」
→ 家老のClaude Codeは停止。足軽がsend-keysしても処理できない
✅ 「起こされたら全確認」方式
→ 足軽がsend-keysで起こす → 家老が全報告ファイルをスキャン → 次のアクション
Claude Codeをマルチエージェントで使う上での根本的な制約です。ポーリング（定期確認ループ）はAPI代金の浪費になるため禁止。非同期イベント駆動にせざるを得ません。
OpenClawではheartbeat（定期巡回）とcronジョブで自然に解決できます。待機コストはゼロです。
3. レースコンディション対策
8つの足軽が並列で動くと、ファイル競合が発生します。
❌ 足軽1 → output.md に書き込み中
足軽2 → output.md に書き込み → 上書き！
✅ 各自専用ファイルに分離
足軽1 → output_1.md
足軽2 → output_2.md
shogunでは「RACE-001」というルールIDまで振って、同一ファイルへの書き込みが禁止されています。競合リスクがある場合は即座にblocked報告を上げさせる設計です。
OpenClawのsessions_spawnは隔離セッションで動作するため、根本的にファイル競合が発生しません。
4. エラーハンドリングの3層構造
shogunでは、エラー発生時のエスカレーションパスが明確に定義されています。
| ステータス | 意味 | 対処 |
|---|---|---|
done |
正常完了 | 戦果テーブルに記録 |
failed |
技術的失敗 | リトライ可否判断 → 別足軽に再割当 or エスカレーション |
blocked |
人間判断必要 | dashboard.md「🚨要対応」セクションに記載 |
足軽 → 家老（リトライ判断）→ 将軍（殿への報告）→ 殿（最終判断）と、4段階のエスカレーションパスがあります。
自分の現行フローでは、司令塔AI（OpenClawメインセッション）が直接判断します。中間層がないため迅速ですが、判断の品質は司令塔の能力に依存します。shogunの3層構造は、エージェント数が多い場合のフィルタリングとして合理的な設計だと感じました。
5. 非同期ステータス共有の工夫
shogunの設計で最も面白いと感じたのが、dashboard.mdによる非同期ステータス共有です。
## 🚨 要対応 - 殿のご判断をお待ちしております
### ライセンス選択【判断必要】
- MIT / GPL / Apache のいずれか
## 🔄 進行中
| 足軽 | タスク | 進捗 |
|------|--------|------|
| 足軽1 | API調査 | 実行中 |
| 足軽3 | テスト作成 | 実行中 |
## ✅ 本日の戦果
| 時刻 | 任務 | 結果 |
|------|------|------|
| 14:15 | DB設計 | ✅ 完了 |
更新は家老のみに限定されています（単一責任で競合防止）。将軍や足軽はdashboard.mdを更新しません。この制約が、情報の一貫性を保証しています。
OpenClawのHEARTBEAT.md（定期巡回時に読み込む指示ファイル）が似た役割を果たしますが、構造化の度合いではshogunのdashboard.mdに学ぶ点があります。エージェント数が増えた際の拡張パターンとして参考になりそうです。
定量比較
| 観点 | shogun（tmux方式） | 現行フロー（Claude Code + OpenClaw） |
|---|---|---|
| セットアップ | bashスクリプト+tmux9ペイン | 設定ファイルのみ |
| 常駐インスタンス | 10（将軍+家老+足軽8） | 1（司令塔のみ） |
| 並列度 | 8固定 | 動的（必要数だけ起動） |
| タスク受け渡し | YAMLファイル経由 | API直接呼び出し |
| 通信安定性 | send-keys依存（不安定） | API経由（安定） |
| トークン効率 | 全インスタンス常駐で消費 | 必要時のみ消費 |
| エラー伝播 | 3層（足軽→家老→将軍） | 1層（直接判断） |
| ファイル競合 | ルールで回避（RACE-001） | 隔離セッションで根絶 |
| 記憶機構 | Memory MCP（知識グラフ） | ファイルベース（MEMORY.md） |
なぜ移行したか
Claude Codeオーケストレーション機能の登場
shogunの導入直後、Claude Code本体にagent teams / orchestration機能が追加されました。
- 将軍の役割 → Claude Codeが内蔵
- 家老の役割 → タスク分解もClaude Codeが自動で処理
- 足軽の役割 → サブエージェントとして自動起動
shogunが解決していた問題の多くが、プラットフォーム側で吸収された形です。shogunの設計が悪かったのではなく、ツールの進化が追いついたというのが正確なところだと思います。
既存のツールで同等のことができた
自分の環境では、OpenClawのsessions_spawn（隔離セッション実行）とClaude Codeのagent teams（並列実装）の組み合わせで、shogunと同等の機能がより少ないセットアップで実現できていました。
# shogunの場合（起動スクリプト + 指示書読み込み）
./shutsujin_departure.sh
tmux attach -t shogun
> "このタスクを実行せよ"
# 現行フローの場合（即座に実行）
sessions_spawn(task="このタスクを実行せよ")
# または Claude Code の agent teams で並列実装
両方を維持する理由がなくなり、shogunは中断しました。
shogunの最大の強み — OSSとしての汎用性
移行の話ばかりしてきましたが、shogunには現行フローにない大きな強みがあります。誰でもすぐに試せるOSSとして公開されていることです。
必要なのはtmux、Claude Code、bashだけ。外部サービスへの依存がありません。git clone して ./shutsujin_departure.sh を実行すれば動きます。
対して自分の現行フローは、OpenClaw、Notion API、Discord連携、独自の運用ルールと多層に絡み合っています。環境固有の設定が多く、そのままOSSとして公開するのは難しい構造です。
| shogun | 現行フロー | |
|---|---|---|
| 必要なもの | tmux + Claude Code + bash | OpenClaw + Notion + Discord + Claude Code |
| 再現性 | 高い（clone → 起動） | 低い（環境固有の設定が多い） |
| 汎用性 | 誰でも試せる | 自分の環境に最適化 |
「シンプルで汎用的」と「強力だが属人的」のトレードオフです。マルチエージェント開発に入門するなら、まずshogunのようなシンプルなOSSから始めるのは良い選択だと思います。
shogunから学んだ設計パターン
設計思想にはツールを問わず応用できるパターンがありました。
1. 単一責任による競合防止
dashboard.mdの更新者を家老だけに限定した設計は、分散システムにおける「ライターは1つ」の原則そのものです。マルチエージェント環境では、誰が何を書くかを明示的に制約することが安定性の鍵になります。
2. 構造化されたエスカレーション
「足軽はblocked報告を上げるだけ、判断は上位に委ねる」という設計は、エージェント数が増えた際にスケールします。現行の「司令塔が全部判断」方式は、エージェント数が少ないうちは最適ですが、スケールには限界がありそうです。
3. ペルソナの使い分け
足軽がタスクに応じて「シニアエンジニア」「テクニカルライター」とペルソナを切り替える設計は面白いです。「戦国風の挨拶だけで、コードはプロ品質」という分離は、AIエージェントの出力品質を上げる実用的なテクニックだと思います。
4. スキル化候補の自動検出
足軽が毎回の報告で「この作業はスキル化できるか？」を自己判断する仕組みがあります。ナレッジマネジメントの自動化として、他の環境でも応用できそうです。
まとめ
マルチエージェントオーケストレーションは、ツールの進化が速い領域です。導入したツールが短期間でプラットフォームに吸収されることもあります。
ただ、multi-agent-shogunのようなOSSを実際に運用したからこそ見えるものがありました。tmuxベースのアプローチで直面する制約を知っているからこそ、API通信の安定性のありがたみがわかります。レースコンディション対策のルール設計を読んだからこそ、隔離セッションの価値が理解できます。
今回の経験で感じたのは、この3点です。
- 最初からshogunを使っていてよかった。 シンプルなOSSで仕組みを理解してから移行したので、現行フローの設計判断に迷いがなかった
- 設計パターンはツールより長生きする。 単一責任、構造化エスカレーション、非同期ステータス共有——これらはshogunを離れた後も活きている
- 移行の判断は早いほうがいい。 2週間で切り替えたのは結果的に正解だった
Discussion