Claude Codeのカスタムエージェント機能（.claude/agents/*.md）を使ってマルチエージェントのSDLC（ソフトウェア開発ライフサイクル）パイプラインを構築したユーザーが、予想をはるかに超えるトークン消費に直面しました。原因を調査したところ、Taskツールの仕組みに起因する根本的な問題が明らかになりました。この投稿は、Claude Codeでエージェントシステムを設計するすべての開発者にとって重要な知見を共有しています。
この記事のポイント
- Taskツールの各呼び出しは、完全に独立した新しいコンテキストとしてエージェントプロンプトをロードする
- CLAUDE.mdも毎回自動的に読み込まれ、共有コンテキストは存在しない
- エージェント定義ファイルが肥大化すると、実作業前に数百万トークンが静的プロンプトの読み込みだけで消費される
問題の背景：マルチエージェント構成の落とし穴
投稿者は、Claude Codeのカスタムエージェント機能を活用して、1つのオーケストレーター（司令塔）が6つの専門エージェントにTaskツールを通じてタスクを委譲するシステムを構築しました。アーキテクチャとしては非常にうまく機能していたものの、トークン使用量が想定を大幅に超えて膨れ上がるという問題に直面しました。
調査の結果、原因はシンプルでした。Taskツールの各呼び出しは、エージェントプロンプト全体を新しいコンテキストとしてゼロからロードするという仕様です。つまり、前回のTask呼び出しで得られた情報や状態は一切引き継がれません。毎回が「初対面」の状態からスタートするのです。
具体的なトークン消費の内訳
投稿者のエージェント定義ファイルは、開発を進めるうちに合計約525KB（7エージェントで12,000行以上）にまで膨らんでいました。オーケストレーター単体でも約100KBありました。
5ステップのパイプラインを1回実行すると、以下のことが起きます：
- オーケストレータープロンプトのロード（約100KB）
- 各サブエージェントがフルプロンプトを新規ロード（各35〜54KB）
- CLAUDE.mdが毎回自動ロードされる
- 各エージェントが同じ状態ファイルを独立して再読み込みする（Task間で共有コンテキストがないため）
- すべてがOpusモデルで実行されていた
これをバッチモードや自動モードで10〜50タスク実行すると、実際の作業が始まる前に、静的なプロンプトテキストのロードだけで数百万トークンが消費されることになります。これはコスト面でも、レート制限の面でも大きな問題です。
得られた教訓と対策
この経験から得られた最も重要な教訓は、Taskツールの呼び出しはコンテキストを共有しないということです。すべての呼び出しは、エージェントプロンプト全体とCLAUDE.mdを含めてクリーンな状態から開始されます。
そのため、エージェントファイルにあらゆるアルゴリズム、ルール、エッジケース、プロトコルをインラインで記述していると、それらすべてに対して毎回トークンコストを支払うことになります。
具体的な対策としては：
- エージェントプロンプトをスリムに保つ：必要最小限の指示だけをエージェント定義に含める
- 詳細な指示は必要な時だけロードする：すべてを事前にプロンプトに埋め込むのではなく、必要に応じてファイルを読み込む設計にする
- CLAUDE.mdの肥大化にも注意する：毎回自動ロードされるため、ここも軽量に保つべき
- モデル選択を考慮する：すべてをOpusで実行する必要があるか検討し、軽量なタスクにはHaikuやSonnetを使うことでコストを抑えられる
知っておくと便利なTips
- カスタムエージェント（
.claude/agents/*.md）を使う場合、各ファイルのサイズを意識的に監視し、定期的に肥大化していないかチェックする習慣をつけると良い - Taskツールの
modelパラメータを活用し、タスクの複雑さに応じてモデルを使い分けることで、トークンコストを最適化できる - 共通の状態情報は、各エージェントが個別に読み込むのではなく、オーケストレーターが読み込んでTaskのプロンプトに含める形で渡すと、重複読み込みを減らせる
まとめ
Claude CodeのカスタムエージェントとTaskツールは、マルチエージェントシステムを構築するための強力な機能です。しかし、Taskツールの「毎回フルコンテキストをロードする」という仕様を理解せずにエージェント定義を肥大化させると、トークン消費が爆発的に増加するリスクがあります。エージェントプロンプトは簡潔に保ち、詳細な指示は動的にロードする設計を心がけましょう。この投稿は、実際にマルチエージェント構成を運用した開発者ならではの貴重な実践知であり、Claude Codeを本格的に活用するユーザーにとって見逃せない情報です。
コメント