Claude Codeマルチエージェント実践｜AI Orchestraで超えた2つの壁
Claude Codeマルチエージェント実践：AI Orchestraの設計と実践
Claude Codeは強力なAIコーディングツールですが、単体で使い続けるとコンテキストの肥大化や役割の曖昧さといった壁にぶつかります。この記事では、25種の専門エージェントとClaude / Codex / Geminiのマルチモデル連携で課題を解決するオーケストレーションシステム「AI Orchestra」の設計思想と実践を紹介します。
マルチエージェントの基本概念については「マルチエージェント構築入門」も併せて参照してください。
きっかけ：課題解決の調査から見つけた2つのアプローチ
Claude Code単体の運用で感じていた課題（後述するコンテキスト溢れと役割混乱）を解決するために、マルチエージェントシステムを自分で作ろうと決めたことです。
調査を進める中で、2つの有力なアプローチに出会いました。1つは松尾研究所のブログ記事、もう1つはNPMで手軽に導入できるOSSのTaktです。
Taktは導入の手軽さが魅力でした。コマンド1つでマルチエージェント環境が整い、Claude CodeやCodexの使い分けもフレームワーク側が吸収してくれます。初動のパフォーマンス向上という点では明らかに優れていました。
一方、松尾研究所のアプローチはClaude Codeのハーネス（Hooks、Agents、Skills）を深く理解した上で自分で構築する必要があります。手間はかかりますが、業界のデファクトスタンダードになりつつあるClaude Codeの拡張機構を根本から理解できます。
最終的に松尾研究所のアプローチを採用しました。自分のキャリアを考えたとき、便利なツールを使うだけではなく、仕組みそのものを理解して自分で作れることに価値があると判断したからです。AI Orchestraの基本思想は、この松尾研究所のブログ記事をベースにしています。
マルチエージェントの概念や構成パターンについては「マルチエージェント構築入門」で整理しています。
Claude Code単体運用で見えた2つの壁
入門記事をまとめる過程で、Claude Codeの単体運用には大きく2つの壁があると実感しました。
壁1: コンテキスト溢れ
Claude Codeでの開発は1つの長い会話で進行します。設計相談をして、実装に入り、デバッグして、レビューを依頼する。この流れの中で会話が長くなると、前半に伝えた設計方針や制約条件が薄れていきます。大きなファイルの分析を依頼した場合も、コンテキストウィンドウ（LLMが一度に保持できる情報量）が圧迫され、他の指示が押し出される形になります。
壁2: 役割混乱
もう1つの壁は、AIの役割が曖昧になることです。「このコードをレビューして」と依頼したはずなのに、レビュー結果を返す代わりに勝手にコードを書き換えてしまう。設計について相談しているつもりが、気づけばコード生成が始まっている。1つのエージェントがすべてを担当しているため、タスクの境界が不明確になるのです。
以下の表に、具体的な症状とAI Orchestraでの解決アプローチをまとめます。
| 課題 | 具体的な症状 | 解決アプローチ |
|---|---|---|
| コンテキスト溢れ | 長い会話で前半の指示を忘れる | サブエージェントにタスク委譲し、要約だけ受け取る |
| コンテキスト溢れ | 大きなファイル分析で圧迫 | 専用エージェント（researcher等）で隔離 |
| 役割混乱 | レビュー依頼したのに勝手に実装変更 | code-reviewer専用エージェントで読み取り専用 |
| 役割混乱 | 設計相談がコード生成に化ける | architect / planner で役割を明確に分離 |
AI Orchestraの設計思想
AI Orchestraの核は「万能モデルに全部やらせる」のではなく「適材適所で専門家に任せる」という考え方です。
25種の専門エージェント
AI Orchestraでは、開発ワークフローの各工程に対応する25種の専門エージェントを定義しています。
| カテゴリ | 数 | 代表例 | 役割 |
|---|---|---|---|
| Planning | 3 | planner, researcher, requirements | タスク分解・調査・要件整理 |
| Design | 5 | architect, api-designer, data-modeler | 設計・API定義・データモデリング |
| Implementation | 9 | frontend-dev, backend-python-dev, debugger | 実装・デバッグ・テスト |
| Review | 6 | code-reviewer, security-reviewer | 品質チェック・脆弱性検出 |
| Documentation | 1 | docs-writer | ドキュメント作成 |
| Utility | 1 | general-purpose | 汎用タスク・CLI委譲 |
各エージェントにはシステムプロンプトで役割と責任範囲が明確に定義されています。たとえばcode-reviewerは「コードの可読性・保守性・バグ検出に集中し、実装の変更は行わない」と指定されています。これにより、レビューを依頼したのにコードを書き換えられるという役割混乱を構造的に防止しています。
マルチモデルの使い分け
AI Orchestraのもう1つの特徴は、Claude以外のLLMを組み合わせている点です。入門記事ではClaude Code単体での構築例を紹介しましたが、AI Orchestraではさらにモデルを跨いだ連携を実現しています。各モデルには得意領域があり、それを活かす設計です。
| モデル | 強み | 担当領域 |
|---|---|---|
| Claude (Opus/Sonnet) | コード実装・オーケストレーション | メインエージェント、実装系全般 |
| Codex CLI | 深い推論・設計判断 | architect, reviewer等の思考が重いタスク |
| Gemini CLI | 1Mトークン文脈・Google検索 | researcher, 大規模コードベース分析 |
モデルの性能差や得意分野については、AIベンチマーク記事も参考にしてください。ベンチマークの読み方を知っておくと、モデルの使い分け判断がしやすくなります。
Claudeがオーケストレーター（司令塔）としてタスクを分配し、深い設計判断はCodex CLIに、大規模なリサーチはGemini CLIにそれぞれ委譲する。こうすることで、各モデルの強みを最大限に引き出しつつ、メインのコンテキストを圧迫しない構成を実現しています。
AI Orchestraの実装：Hook・並列レビュー・マルチモデル連携
ここからは、AI Orchestraの実装を3つの機能に絞って紹介します。
Hookによる自動ルーティング
AI Orchestraの中心にあるのがagent-router.pyというHookです。Claude CodeにはUserPromptSubmitフック（ユーザーの入力を受け取った直後に実行される仕組み）があり、このフックがユーザーの発言を分析して適切なエージェントやCLIツールを自動で提案します。
# ユーザーの発言を分析し、適切なエージェントを提案
# 「セキュリティ大丈夫？」→ security-reviewer を提案
# 「この設計どう思う？」→ architect (+Codex) を提案
# 「最新のライブラリ調べて」→ Gemini CLI を提案
具体的には、日本語・英語両方のトリガーワードを辞書として保持しており、ユーザーの入力にマッチするキーワードがあれば対応するエージェントを提案します。「意識しなくても適切なエージェントが使われる」というUXを目指した仕組みです。
/review で並列レビュー
AI Orchestraでは/reviewという1つのコマンドで、6種のレビュアーを並列に起動できます。
/review # 以下が並列実行される
# → code-reviewer: 可読性・保守性・バグ検出
# → security-reviewer: 脆弱性・権限チェック
# → performance-reviewer: 計算量・I/O最適化
# → spec-reviewer: 仕様との整合性
# → architecture-reviewer: アーキテクチャ妥当性
# → ux-reviewer: UX・アクセシビリティ
それぞれが独立したサブエージェントとして動作するため、レビュー中にメインのコンテキストは消費されません。各レビュアーの結果は重大度別に集約され、統合レポートとして表示されます。/review impl（実装系のみ）や/review design（設計系のみ）のように、目的に応じて実行範囲を絞ることもできます。
Codex/Gemini マルチモデル連携
設計判断やトレードオフ分析のように深い推論が求められる場面では、Codex CLIに処理を委譲します。一方、ライブラリの最新情報を調べたり、リポジトリ全体の構造を把握したりする場面ではGemini CLIが活躍します。
どちらの場合も、サブエージェント経由で呼び出すことがポイントです。Codex/Geminiの出力は長大になることがあるため、直接メインのコンテキストに流し込むと圧迫してしまいます。サブエージェントに「実行して、結果を要約して返して」と依頼することで、メインのコンテキストには要約だけが届く仕組みになっています。
運用して分かったこと
AI Orchestraを日常の開発で使い始めて、いくつかの発見がありました。
良かった点
- コンテキスト保護が効果的に機能している。長時間の開発セッションでも、前半の指示が抜け落ちる問題がかなり軽減された
- レビュー品質が向上した。6種のレビュアーが並列で動くため、セキュリティやパフォーマンスの見落としが減った
- モデルの使い分けが自動化された。Hookによるルーティングのおかげで、意識しなくても適切なモデルに振り分けられる
改善余地
- エージェント定義のメンテナンスコストがある。25種のシステムプロンプトを適切に保つには継続的な調整が必要
- Hookのルーティング精度は万全ではない。キーワードベースのため、文脈によっては不適切なエージェントが提案されることがある
デプロイは/init-orchestraスキルで有効化でき、dotfiles管理によってプロジェクト間で設定を共有しています。新しいプロジェクトを始めるときも、すぐにオーケストレーション環境を使い始められます。
今後の展望
AI Orchestraは現在GitHubで公開しています。まだ個人開発での運用がメインですが、今後はいくつかの方向で発展させたいと考えています。
まずは汎用化とドキュメント整備です。現状は自分の開発スタイルに最適化されている部分が多いため、他の開発者でも導入しやすい形に整えていきたいです。
次に、実案件での検証です。個人プロジェクトでは十分に機能していますが、チーム開発や規模の大きいコードベースでどこまで通用するかは未知数です。実際のプロジェクトで試して知見を蓄積していきます。
将来的には、エージェントの自律進化も構想しています。使用ログから指摘パターンを学習し、エージェント自身がシステムプロンプトを改善する仕組みです。
「AIに仕事を任せる」のではなく「AIとチームを組む」。AI Orchestraは、そうした開発スタイルを探求するための実験場です。マルチエージェントの世界に興味がある方は、まず入門記事で全体像をつかんだ上で、ぜひ自分の環境で試してみてください。
Comments