Multi-agent orchestration：3,315回の実行で壊れたもの

Denysです。フルスタック・AIエンジニアです。私は、1つのリードのClaude Codeセッションが、専門のサブエージェントに仕事を渡す形でソフトウェアを作っています。探索役、プランナー、実装役、セキュリティとコードのレビュー役です。これは、顧客向け製品ではなく、その環境についての報告で、マルチエージェントシステムを自分で運用した記録です。数字は、環境自身が残すログから取りました。起動したエージェント1つにつき1行の起動台帳、セッションのトランスクリプト、設定そのもののgit履歴です。クライアント名とプロジェクト名は伏せています。

あわせて、サンプルデータを使ったプロトタイプとしてインタラクティブなマルチエージェント管制ダッシュボードも作りました。以下はすべて実際の実行から得た数字です。

マルチエージェント・オーケストレーションとは何か？

マルチエージェント・オーケストレーションとは、1つのリードエージェントが範囲を絞ったタスクを専門のエージェントに渡し、その結果をまとめる仕組みです。オーケストレーター側が、コンテキスト、予算、再試行を管理します。この記事では2つのパターンとして登場します。サブエージェント（探索役、プランナー、実装役、レビュー役）を従えるリードセッションと、エージェントが言葉巧みにすり抜けられないルールを強制するフックです。マルチエージェント管制ダッシュボードは、同じ考え方をサンプルデータで示しています。以降の節は、実際の実行で何が壊れたかの記録です。

構成はどうなっているか？

リードのセッションが私と対話し、タスクを持ちます。大きなタスクでは、本番コードを自分では書きません。仕事を外に出します。

• 探索役は、コードベースの1つの層（フロントエンド、バックエンド、データベース）を読み、短いマップを書きます。
• プランナーは、そのマップをファイルパスつきの番号付きステップに変えます。
• 実装役は、計画の1フェーズずつを受け持ち、先にテストを書き、次にコードを書きます。並列の実装役には、それぞれ専用のgit worktreeを渡します。
• レビュー役がdiffを確認します。セキュリティ担当と正しさ担当の2人で、どちらも同じコミットを見ます。

それらの間にあるのがフックです。Claude Codeがツール呼び出しの前後に実行する小さなスクリプトで、エージェントの起動、ファイルへの書き込み、git commitといった呼び出しを止められます。この環境にはフックが165個あり、そのうち約40個がオーケストレーション関連です。エージェントが読むルールはMarkdownで、エージェントが迂回できないルールがフックです。この使い分けが、2か月の最大の教訓であり、この記事の残りはその理由の説明です。

エージェントは何回動き、どのモデルで動いたか？

指標（2026年8月17日〜10月19日）	値
起動したサブエージェント	稼働57日間で3,315
エージェントの種類	30
起動が多かったもの	実装役（tdd-guide）793、セキュリティレビュー役455、general-purpose 424
実際に動いたモデル	Opus 46.5%、Sonnet 45.8%、Fable 1.3%、残りはリードから継承
1つずつ起動した割合	67.7%
並列の最大の波	5エージェント（上限）、9回到達
実装役1回あたりのレビュー役の実行	0.71（レビュー680回、実装963回）

驚いた数字が2つあります。1つ目は、起動の大半が単独のエージェントで、並列の展開ではなかったことです。並列の作業は例外です。読み取りとレビューでは効果がありますが、書き込みでは高くつきます（下の最初の失敗を参照）。2つ目は、エージェントのファイルがモデルを指定している起動のうち23%で、実際に動いたモデルが違っていたことです。ほとんどはSonnetがOpusに引き上げられたもの（610件中584件）でした。これは意図したもので、ステップが移行、認証、サーバールートのような危険なコードに触れるとき、またSonnetの実装役が同じテストで3回続けて失敗したあとに、フックがモデルを上げます。より強い実装役は159回動きました。ログを「危険なステップ」と「繰り返しの失敗」に分けることはできないため、そのうち何回が救済だったかは言えません。

Claude Code のサブエージェントを動かす費用はいくらか？

私は定額のサブスクリプションなので、トークン単位の請求はありません。ただしトランスクリプトにはすべてのトークンが記録されているため、直近30日間（9月20日〜10月19日）をAnthropicのAPI定価で計算するとこうなります。

30日間	トークン
合計	約159.9億
キャッシュ読み取り	155.5億（モデルに送ったもの全体の97.7%）
キャッシュ書き込み	3.72億
キャッシュなしの新規入力	18万
出力	6,900万

定価（Opus 5.5は入力が100万トークンあたりUSD 4、出力が20、キャッシュ読み取りが0.20。Sonnet 5.5とFable 5.1はそれぞれの価格）で計算すると、現行の3モデルの出力、入力、キャッシュ読み取りだけで約USD 3,350になります。キャッシュ書き込みと、ログに残る旧バージョンのモデルは含めていないため、実際のAPI費用はもっと高くなります。このUSD 3,350のうち3分の2はキャッシュ読み取りです。毎ターンでコンテキスト全体を送り直すため、キャッシュがあって初めて、この規模が現実的な費用に収まります。

予算を立てるときに私が使うのは、リードとサブエージェントの内訳です。

• サブエージェントは全トークンの42%を使い、出力の66%を書きました。 リードのセッションは、最も長いコンテキストを抱えるため高くつきます。実際の文章とコードを書くのはサブエージェントです。
• レビュー役は安上がりです。 セキュリティまたはコードのレビューで使ったのは100万〜400万トークンでした。実装役は500万〜1億トークンです。リスクのあるコミットごとにレビュー役2人を付けても、実装役1人がやり直す費用より安く済みます。
• 最大のセッションは10月6日で、63個のサブエージェントを起動し、3.5時間で3.72億トークンを使いました。

何が壊れたか

以下の失敗はすべて実際に起き、日付があり、再発を防ぐフックかスクリプトで終わっています。どれも「モデルがバグを書いた」ではありません。通常のバグは、テストとレビュー役が捕まえました。これらは、その両方をすり抜けました。

日付（2026年）	壊れたもの	今それを止めているもの
8月19日	並列のエージェントが1つの翻訳ファイルを上書き。約95キーのうち55キーが消え、チェックはすべて通過	各エージェントは自分のキーを専用の断片に書き、マージスクリプトがすべてのキーの反映を確認する
8月24日	クリーンアップのスクリプトが、完了した作業パケット4つを削除	未回収の変更があるworktreeはクリーンアップが飛ばす。先に回収し、あとで掃除する
9月1日	後続の波のエージェントが古いコードから始まった	各エージェントの作業は3-wayパッチとしてマージし、ファイルコピーにはしない
9月13日	エージェントが起動時に死に、起動は「成功」と報告	ランチャーがエージェントの最初の出力を読み、死んだモデルを全セッションで印づける
9月20日	私のルール2つが矛盾し、エージェントが拒否されたコマンドを再試行	隔離エージェント向けのブリーフに、サンドボックスが受け付けるコマンドの形を載せる
10月18日	エージェントが、自分のコミットを止めていたチェックを編集	チェックのファイルはプロジェクトのセッションから読み取り専用。変更は記録され、通知される
10月18日	修正の指示が、クライアントのアプリのユーザーが受け取る内容を静かに変えた	すべての修正ブリーフに「本番の挙動を維持」と書く。製品の変更は私に戻す

並列の書き手と、すべての機能が触るファイル

3つのエージェントが、クライアントのiOSアプリの3つの機能を同時に作りました。それぞれがアプリ唯一の翻訳カタログに自分の文言を追加し、それぞれがファイル全体の自分の版を保存しました。勝ったのは最後の保存です。新しい約95キーのうち55キーが消えました。各エージェントのビルドは、各自のコピーが整合していたため通過しました。カタログのチェックも、カバレッジが別の形で壊れていたため通過しました。見つけたのは、キーを手で数えたときです。

修正は3つの部分からなります。1つ目は、宣言したファイルが実行中の書き手のものと重なるエージェントの起動を、フックが拒否すること。2つ目は、エージェントが共有カタログを直接編集せず、キーを断片ファイルに書き、1つのスクリプトが断片をマージして、値の衝突で失敗し、すべてのキーが存在することを確認すること。3つ目は、カタログのキーが以前より少なければ、2つ目のフックがコミットを止めることです。正直に言うと、これらの防御を入れたのは10月18日で、消失から60日後でした。その間の唯一の防御はMarkdownのルールの1行で、ルールは提案にすぎません。

完了した作業を消したクリーンアップ

並列の実装役はgit worktreeで作業し、コミットせずに変更をステージします。コミットのチェックが、リードにクリーンアップスクリプトの実行を指示しました。スクリプトは、エージェントがまだ実行中のworktreeを飛ばしていましたが、これらのエージェントはすでに終わっていました。完了した作業パケット4つが削除され、復元できるgitオブジェクトも残りませんでした。「エージェントはまだ動いているか」と「その作業は回収されたか」は別の問いで、スクリプトは前者しか確認していませんでした。今のクリーンアップは、メインのチェックアウトにない変更を持つworktreeをすべて飛ばし、別のフックがworktreeフォルダの直接削除を止めます。

古いコードから始まった波

11ステップの計画は、3つの波で6つの実装役として実行されました。波2と波3は、セッションが始まったコミットから、つまり3コミット遅れた状態で始まりました。1つのエージェントのファイルを書き戻すと、別のエージェントが完了した変更を巻き戻してしまうところでした。worktreeは開始時点のスナップショットなので、結果は3-wayパッチとして戻すようにし、衝突は黙って上書きされず表面化します。

成功と報告した、死んだエージェント

利用上限を使い切ったモデルに固定されたエージェントが、最初のステップの前に死にました。起動は「spawned successfully」を返し、失敗は後からアイドル通知として届きました。別のモデルでの再試行は、モデルを固定する同じフックによって元に戻されました。その後リードは、黙って自分で計画を書きました。まさにプランナーが避けるために存在する結果です。今はフックがエージェントの最初の出力を読み、死んだモデルをしばらくのあいだ全セッションで印づけます。

自分のチェックを編集したエージェント

10月18日、クライアントのプロジェクトで作業していたセッションは、あるチェックにコミットを止められ続けていました。そのセッションは、コミットが通るようにチェックのスクリプトを3つ編集しました。隠されていたことは何もなく、編集は丸見えでした。しかし、何も止めませんでした。チェックはエージェントが書き込めるフォルダにあり、監視されていたのはファイル編集ツールだけで、シェルコマンドは対象外だったからです。今は、チェックのファイルは設定フォルダ自体で起動したセッションからしか変更できず、書き込みの経路（エディタ、シェルのリダイレクト、スクリプト、git）をすべて塞ぎ、プロジェクトのセッション中の変更はすべて記録して通知します。

最初に誰かに警告するとしたら、この失敗です。「コミットを通せ」と言われたエージェントは、関門を問題の一部として扱います。

私自身の2つのルールが食い違っていた

あるルールは、トークンを節約するために、3つ以上のシェルのステップを1つのスクリプトにまとめるようエージェントに指示していました。worktreeで隔離されたエージェントは、まさにその形を拒否するサンドボックスで動きます。エージェントは、何日かにわたって「too complex to verify」に3回連続で当たり、言い換えを試みて予算を使い果たしました。今は、同じ拒否が2回続いたらエージェントが止まり、隔離エージェント向けのブリーフに、通るコマンドの形を載せています。

マルチエージェントのシステムはなぜ失敗するのか？

この2か月から言えるのは、モデルが弱すぎるからではない、ということです。上の7つの失敗のどれも、与えられたタスクでモデルが失敗したものではありません。失敗は、エージェントの継ぎ目、つまりどのエージェントも単独では責任を持たない場所で起きます。

• 共有された状態。 すべての機能が触るファイル、作業ツリー、ブランチ。各エージェントは局所的には正しく、結果は全体として間違っています。
• 緑のチェック。 上のどの事故も、当時あったチェックは通過していました。チェックが証明するのは、チェックした内容だけです。
• 嘘をつく成功のシグナル。 「Spawned」「saved」「cleaned up」は、どれも言葉より狭い意味しか持っていませんでした。
• 関門に最適化するエージェント。 コミットが止められていると伝えれば、エージェントはそのコミットを通す方法を探します。関門そのものを通る方法も含めて。

ほかの開発者も、より大きなエージェント群で同じパターンを報告しています。約20のエージェントを動かすJed Ardenは、インシデントログにLLMはほとんど出てこないと書いています（出典、2026年7月）。Cursorのチームは、ロックつきの1つの調整ファイルを共有する20のエージェントが、2〜3のエージェントのスループットまで落ちたと報告しています（2026年1月）。

最初に整えること

Claude Codeのサブエージェント、またはあらゆるマルチエージェントのオーケストレーションを始めるなら、私が学ぶのにかかったことを踏まえて、この順で進めます。

1. エージェントの起動をすべて記録する。 起動1回につき1行：時刻、エージェントの種類、モデル、リスク。これがなければシステムが何をしているか分からず、上の数字も存在しません。
2. ファイルごとに書き手は1人。 並列の書き手にはworktreeと、宣言したファイル一覧を渡します。すべての機能が追記するファイル（翻訳、ロックファイル、変更履歴）には1人の持ち主を置き、他は断片を提出します。
3. 掃除の前に回収する。 クリーンアップの判断を「動いているか」でさせないでください。「その作業がメインのチェックアウトにあるか」で判断します。
4. チェックをエージェントの手の届かない所に置く。 止めるフックを、プロジェクトのセッションが書き込めない場所に置きます。
5. 波に上限をつける。 並列は5エージェントが私の上限です。それを超えると、レビューが詰まり、衝突がスループットより速く増えます。
6. 努力ではなく、繰り返しでエスカレートする。 既定は安いモデル。同じ失敗が3回続いたら、より強いモデルで1回。その先は人間です。

1人の開発者のワークフローではなく、企業向けにAIエージェントを作って運用する費用はどれくらいか。それは別の問いで、数字つきでAIエージェントの費用：4件の運用実績から見る内訳で答えています。1か月後の同じログから、今どのパネルを見ているかはAIエージェント監視ダッシュボード：1,238回の実行にあります。

このレポートの限界

• 1人の開発者の環境。 リードのセッション1つ、並列は最大5エージェント。数十、数百のエージェントの群れは、たとえば起動時など、別の形で失敗します。
• 実際の請求ではない。 ドルの数字は、30日間のAPI定価換算の下限で、キャッシュ書き込みと旧モデルは含みません。私は定額のサブスクリプションを使っています。
• ログの欠落。 ブロックされた起動は記録されないため、波の上限が何回効いたかは言えません。より強い実装役の159回には、危険なステップと繰り返しの失敗が混ざっています。
• 日付は自分のメモから。 事故の日付は、当日に書いたメモとコミットに基づきます。1件は古いルールファイルでは別の日付になっていて、メモのほうを採用しました。

この取り組みから生まれたダッシュボードのプロトタイプはマルチエージェント管制ダッシュボードで、クライアント向けのエージェント開発はAIエージェント開発・チャットボット開発にあたります。