はじめに — AIコーディングのコスト問題はどこにあるのか

Claude CodeやCursorをチームで導入した方なら共感いただけると思いますが、シートライセンス料よりもトークンコストのほうがはるかに深刻です。2028年にはAIコーディング費用が平均開発者の年収を超えるという予測も出ています。

問題は、このトークンの大部分が**「思考」ではなく「I/O」**だという点です。具体例を挙げます。

  • メソッド1つの説明を聞くためにファイル5つを丸ごと読む
  • 隣にあるテストファイル20個と全く同じパターンで新しいテストファイルを生成する
  • 会議の後にドキュメントを更新する

こうした作業で数千トークンが消えていきますが、実際の推論（reasoning）はほとんどありません。にもかかわらず、これをすべてフロンティアモデルに投げています。オーバースペックなモデルを単純作業に使っているわけです。

本記事では、高価なモデルは本当に推論が必要な場面にのみ使い、雑務は安価なワーカーモデルに委譲するモデルルーティングパターンを解説します。根拠資料はSpotify Engineeringブログです。

日本の開発現場では、レガシーコードベースのコンテキストを毎回読み直す必要があるケースが多く、この最適化の効果が特に出やすいと考えられます。

Developer terminal showing Claude Code session with token usage dashboard and AI model routing interface Dev Environment Setup

核心的な構造 — 2つのモードによるルーティング

基本的なアイデアはシンプルです。**エフェメラルランタイム（ephemeral runtime）上で動作する宣言的エージェント（declarative agent）**を2つ作成し、重いI/Oとボイラープレート作業を委譲します。

ワーカーモデルの設定（例：Gemini 2.5 Flash）

# Mode 1: 大容量ファイル読み取り専用ワーカー
name: bulk-reader
description: コード分析用の大容量ファイルリーダー - Claude CodeのI/Oを委譲
instructions: |
  あなたは精密なコードアナリストです。提供されたファイルを読み、質問に簡潔に答えてください。
  構造化された箇条書きのみを出力してください。挨拶、説明、前置きは禁止です。
  各項目は正確な名前、型、行番号で始めてください。
  詳細はネストした箇条書きを使用してください。要求されていない内容は省略してください。
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

# Mode 2: ボイラープレートコード生成ワーカー
name: code-writer
description: ボイラープレートコード生成器 - Claude Codeの出力負荷作業を委譲
instructions: |
  あなたは仕様と参照ファイルに基づいてコードファイルを生成します。
  既存のパターン、規約、命名、スタイルを正確に踏襲してください。
  コードのみを出力してください。説明やMarkdownフェンスは要求されない限り禁止です。
  仕様が曖昧な場合は、参照コードのパターンに合うよう合理的に選択してください。
visibility: public
model: gemini-2.5-flash
resourceLimits:
  temperature: 0.2
tags:
  - coding
  - delegation

**「コードのみを出力してください」**という指示が地味に重要です。これがないと、モデルがMarkdownフェンスと説明文を付けてしまい、Claudeがそれを再度パースする無駄が発生します。

ルーティングの3層構造

  1. Hooks層 — PreToolUseフックで全ツール呼び出しの前に介入します。ファイルが閾値（デフォルト350行）を超えると読み取りをブロックし、ワーカーへリダイレクトします。
  2. Scripts層 — Portal CLIをラップしたbashスクリプトが、リクエスト構築、エラー展開、トークン使用量のstderr報告まで処理します。
  3. Skills層 — Claudeにいつ・どうスクリプトを呼ぶかを伝えるMarkdownスキルファイルです。

この階層構造の利点は、**優雅に性能劣化する（degrades gracefully）**点です。Claudeがスキル説明を読まなくても、フックが高コストな読み取りをブロックします。

# 単一ファイルではなく複数ファイルを一括委譲
bulk-read --question "このサービスは何をするのか？" \
  --paths src/Service.java src/Handler.java

# 参照ファイルベースでテストコードを生成
code-write --spec "UserServiceのテストを作成" \
  --reference tests/OrderTest.java \
  --target tests/UserTest.java

ベンチマーク結果

Javaモノレポで4シナリオをテストした結果、平均約90%のトークン削減が確認されました。特にcode-writeシナリオはトークン測定自体が困難です。委譲なしではClaudeが参照ファイルを読み、出力トークンとしてコードを生成する必要がありますが、委譲後はコードが直接ディスクに書き込まれ、Claudeはそれを見ることすらありません。

Ephemeral serverless agent runtime architecture diagram connecting Claude Code to worker models Programming Illustration

注意事項 — 委譲してはいけないもの

このパターンは万能ではありません。実務で必ず守るべき境界があります。

❌ 編集（Editing）は委譲不可

ワーカーモデルの要約には信頼できる行番号が含まれません。Claudeが分析結果に基づいて編集する必要がある場合、該当セクションは直接読む必要があります。そのため、フックはoffset/limitによるターゲット読み取りを許可するよう設計されています。

❌ 推論（Reasoning）は委譲不可

テスト中、ワーカーモデルは表面的なパターンはうまく見つけましたが、微妙なスレッドセーフティ（thread-safety）バグを見逃しました。Claudeは正確なコンテキストを与えると数秒で発見しました。そのため、ルーティング規則ではデバッグ、アーキテクチャ決定、安全性クリティカルなコードは明示的に除外しています。

⚠️ レイテンシ（Latency）の累積

委譲1回はネットワーク往復です。Claude Code → Portalバックエンド → ワーカーモデル → 戻り。通常10〜30秒かかり、単一呼び出しは30秒でキャップされます。大きな読み取りには問題ありませんが、小さな読み取りには逆効果です。行の閾値が存在する理由がこれです。

📊 コスト対効果の判断基準

状況委譲可否理由
350行以上のファイル全体読み取り✅ 委譲コンテキストに入らないため削減効果が最大
特定メソッドのみ確認❌ 直接ターゲット読み取りのほうが速い
テスト/設定ボイラープレート生成✅ 委譲パターンが明確
デバッグ、アーキテクチャ設計❌ 直接推論品質が決定的
安全性クリティカルなコード❌ 直接ワーカーが見逃すリスク
パイプコマンド（cat file | grep）❌ 直接既にターゲット読み取り

🇯🇵 日本の開発現場での適用コンテキスト

日本の受託開発やSIer案件では、プロジェクトごとにコード規約が大きく異なるため、ワーカーモデルの参照ファイルマッチングが特に重要です。code-writeを使う際は、必ずそのプロジェクトの既存ファイルをreferenceに指定してください。そうしないとプロジェクトに合わないコードが生成されます。

また、社内ネットワーク環境ではPortalインスタンスの自社ホスティングが必要になり、外部モデルAPI呼び出しがブロックされている可能性があります。その場合はローカルLLM（Ollama等）をワーカーとして使う構成も検討してください。Gemini Flashの代わりにQwenやLlama系を接続すれば、コストはほぼゼロになります。

AIコーディングツールのインフラレベル理解が必要な方は、VS CodeでGoogle Cloud ML開発を完結させるWorkbench拡張機能の完全ガイドもあわせてご覧ください。開発環境自体をクラウドに上げる観点で関連する内容です。

Token consumption benchmark chart comparing direct file reads versus delegated bulk-reader summaries Algorithm Concept Visual

まとめ — ルーティングは設定問題であり、インフラ問題ではない

このパターンの真の価値は、モデルルーティングをシステムエンジニアリング問題から設定問題へと変える点にあります。インフラを構築する必要はありません。望むものを記述し、名前を付けるだけです。

モードの再利用性・共有性・組み合わせ性を整理すると：

  • 再利用可能 — 同じbulk-readerとcode-writerモードがすべてのプロジェクトで動作
  • 共有可能 — チーム全体が同じモードを使用
  • 組み合わせ可能 — doc-writer、reviewer、translatorモードを追加可能
  • 決定とワーカーの分離 — プラグインはいつ委譲するか、モードはどう応答するかを決定

次のステップ学習の方向性

  1. モデルルーティングパターンをチームの規約として文書化してください。どの作業をどこへ送るか明示的なルールがあってこそ一貫性が生まれます。
  2. トークン使用量の計測を先に行ってください。削減効果を測定できなければ最適化もありません。
  3. ワーカーモデル交換の実験を行ってください。Gemini Flash → Claude Haiku → ローカルLlamaの順にコスト/品質トレードオフを比較すれば、チームに合うポイントが見つかります。

結局この話は、**「GPU上で行われる推論最適化」**と同じ文脈です。NVIDIA、MLPerf Inference v6.0で291回優勝…Blackwell Ultra GPUによる推論性能の独走のようなハードウェアレベルの最適化ニュースと併せて見ると、ソフトウェアルーティングとハードウェア性能がどう噛み合うかが理解できるでしょう。

トークンを節約するのは、結局**「どこにどのモデルを割り当てるか」**の問題です。インフラチームがなくても、今日から始められます。

本コンテンツは、信頼性の高い情報源をもとにAIツールを活用して作成され、編集者によるレビューを経て公開されています。専門家によるアドバイスの代替となるものではありません。