なぜClaude Code開発はトークン破産するのか。ローカルLLMのGemmaに作業を委譲してAPIコストを削る訳

息をするようにトークンが消える

コンテキストウィンドウ20万トークンは圧倒的だ。

だが、日本語でやり取りし、テストやLintまで任せると一瞬でトークン破産する。

ルーチン作業をローカルLLMに逃がす。

31BパラメータのGemma4-31B-ITモデルをサブエージェントとして繋ぐ。

これでAPIコストの出血は止まる。

ただし、GPUのファンが爆音で鳴り続ける。

エージェント開発のパラダイムシフト

エージェント運用の致命的な課題は「APIコストの爆発」と「コンテキスト汚染」だ。

解決策として、複数のアプローチが統合されつつある。

1つ目は、ローカルLLMのサブエージェント化だ。

31Bパラメータのモデルを量子化し、コンシューマ向けGPUで動かす。

これをファインチューニングし、エージェント型コーディングに特化させる。

Function CallingやReAct推論の精度を上げる。

構造化されたJSONを即座に出力させる。

これをMCPサーバー経由でメインエージェントから呼び出す。

APIトークンを一切消費せず、ファイル探索やコードレビューを委譲する。

学習データは1,546サンプル。学習時間は約1.5時間だ。

2つ目は、ハーネスエンジニアリングの徹底だ。

プロンプトによる「助言」の限界を認め、環境の設計でAIを制御する。

CLAUDE.mdは200行以内に抑える。

ETH Zurichの研究では、指示を詰め込みすぎるとトークンコストが20%以上増加する。

タスク解決率は全く改善しない。

だから、Hookで確定的にフォーマットを強制する。

Permissionで危険な操作を物理的にブロックする。

環境全体を8つの次元で診断し、24点満点でスコアリングするスキルもある。

プロンプトエンジニアリングから、システム設計への移行だ。

3つ目は、言語特性を考慮した記憶の外部化だ。

日本語は英語の2〜3倍のトークンを消費する。

日本語で記憶を保存すると、保持できる情報量が激減する。

だから、普段のやり取りは日本語でも、記憶やドキュメントの記録は英語で行う。

これにより、AIの記憶容量を実質的に拡張する。

コスト節約のためにセッションを切断すると、古い意思決定が断絶する。

推論精度が劣化する現象が起きる。

これを防ぐために、隔離されたサブエージェントに雑用を任せる。

メインセッションの貴重な文脈を無傷のまま保護する。

開発者目線：コンテキスト・アーキテクチャの全貌

エージェントは単なるCLIではない。

インフラストラクチャだ。

しんたろー：
API代の増加ペースを見ると、ローカルLLMへのオフロードは避けられないと思った。
便利だからと全部クラウドに任せるのは罠かもしれない。
ローカルLLMに逃がせる作業の切り分けが気になっている。

プロンプトエンジニアリングからシステム設計へと移行している。

どのタスクをローカルLLMに逃がすかを設計する。

すべてをメインモデルに処理させるのは非効率だ。

ファイル探索、Lint修正、テストライブラリのアップデート。

これらはメインの文脈を全く必要としない。

無関係な出力がメインセッションに混ざることで、コンテキストが汚染される。

だから、サブエージェントを使う。

サブエージェントの価値は、単なるタスク分割ではない。

APIコストの削減とコンテキストの隔離という二重の最適化だ。

ローカルLLMなら、APIトークンを消費しない。

20GBのVRAMがあれば、4-bit推論で31Bモデルが動く。

コンシューマ向けGPUで動作する。

Gemma4-31B-ITはマルチモーダルアーキテクチャだ。

商用利用可能なApache 2.0ライセンスで提供されている。

ベースモデルの段階で、日本語コーディング能力が9.4/10と高い。

これをQLoRAでファインチューニングする。

4-bit NF4やdouble quantizationといった技術を使う。

Function Callingのスコアが+2.0向上する。

Multi-step ReActのスコアも+2.0向上する。

そして、日本語のトークン消費問題だ。

日本語は英語の2〜3倍のトークンを消費する。

だから、記憶の外部化戦略をとる。

しんたろー：
日本語のトークン消費量が英語の2〜3倍というのは驚いた。
ずっと日本語でチャットしていると、コンテキストが溢れるのも納得だ。
ドキュメント化だけ英語に切り替えるアプローチが気になっている。

作業終了時に、決定事項やエラー回避策を英語で書き出させる。

次回のセッションで、そのファイルをピンポイントで参照させる。

これでコストを抑えつつ、文脈を復元できる。

エージェントには自動で記憶を保持する機能がある。

しかし、これは無限のストレージではない。

毎ターンの先頭にテキストとして自動注入される仕組みだ。

記憶が増えるほど、20万トークンの枠を圧迫し続ける。

だからこそ、記録する言語の選択がコストを左右する。

英語で記録するだけで、実質的な記憶容量が2〜3倍になる。

さらに、ハーネスエンジニアリングだ。

同じミスを何度も繰り返すAIに、毎回プロンプトで指示するのは無駄だ。

次のセッションではまた同じことが起きる。

設定ファイルに書いても、指示が増えるほど守られなくなる。

これはプロンプトの限界だ。

だから、環境の仕組みで物理的に防ぐ。

Hookは100%発火する確定的な制御だ。

フォーマットの強制やファイル保護は、Hookで実装する。

Permissionの拒否ルールは常に勝つ。

バイパスモードであっても、拒否ルールが優先される。

危険な操作を明示的に拒否し、安全な操作だけを許可する。

セキュリティのベースライン以外は、実際にAIがミスを犯してから設定を追加する。

大量のHookを入れるのはアンチパターンだ。

設定が複雑になるだけで、エージェントの動きが鈍くなる。

必要な制御だけを、必要な場所に配置する。

実務への影響：コンテキスト・アーキテクチャの構築

コンテキスト・アーキテクチャを自ら構築する。

まず、設定ファイルのダイエットだ。

CLAUDE.mdは200行以内に抑える。

深い情報が必要なら、別ディレクトリのルールファイルとして段階的に読み込ませる。

Hookやテストの出力は、成功時は抑制する。

エラー時のみ表示させる。

フルテストスイートの出力がコンテキストに流れ込むと、AIが迷走する。

次に、サブエージェントの活用基準を見直す。

フロントエンドやバックエンドといった役割分担ではない。

コンテキストの隔離を基準に委譲する。

メインの複雑な実装中に発生した、独立したタスク。

これをローカルLLMのサブエージェントに任せる。

MCPサーバーを経由すれば、連携できる。

しんたろー：
サブエージェントの使いどころは、役割分担ではなくコンテキストの隔離だという視点にハッとした。
メインの思考を邪魔させないための隔離部屋として機能するのか。
Lintエラーの修正などをローカルモデルに投げる運用を試してみたい。

そして、言語戦略の徹底だ。

普段のやり取りは日本語で行う。

プロジェクトの記憶やドキュメント化は英語で行う。

「今日の作業で決定したデータモデルの変更理由を、英語でドキュメントに追記して」

この一言をセッション終了前に挟む。

これだけで、次回のトークン消費が1/2〜1/3に抑えられる。

AIの行動をプロンプトで制御しようとするアプローチは限界がある。

「常にXを使え」「絶対にYをするな」といった絶対ルールは脆弱だ。

理由を説明することで、AIがエッジケースに対応できるようにする。

環境の設計で品質を担保する。

トークン破産を防ぎ、推論精度を維持する。

ローカルLLMの導入も選択肢に入る。

商用利用可能なモデルを選び、環境に合わせて調整する。

すべてをクラウドに依存するリスクを減らす。

APIコストの最適化は、単なる節約ではない。

エージェントの知能を引き出すための戦略だ。

無駄なコンテキストを削ぎ落とし、必要な情報だけを渡す。

トークンの無駄遣いは、開発スピードの低下に直結する。

アーキテクチャの設計次第で、生産性は変わってくる。

よくある質問と回答

APIコストを抑える具体的な方法は？

3つのアプローチがある。

1つ目は、ルーチン作業をローカルLLMのサブエージェントに委譲することだ。

MCPサーバー経由で連携できる。

2つ目は、CLAUDE.mdを200行以内に抑えることだ。

Hookの出力をエラー時のみに制限し、無駄なコンテキスト流入を防ぐ。

3つ目は、プロジェクトの記憶やドキュメント化を英語で行うことだ。

日本語によるトークン消費の膨張を防ぐ。

実質的な記憶容量を2〜3倍に拡張できる。

サブエージェントはどのようなタスクに使うのが適していますか？

フロントエンドやバックエンドといった役割分担ではない。

コンテキストの隔離を基準に委譲する。

メインの複雑な実装中に発生したテストライブラリのアップデートやファイル探索。

あるいはLint修正などだ。

メインの文脈を必要としない独立したタスクを任せる。

メインの文脈を汚染したくないタスクを任せる。

ハーネスエンジニアリングとは何ですか？

設定ファイル、Hook、Permissionなどの設定群を体系的に設計することだ。

AIの行動を環境の仕組みによって制御する手法を指す。

毎回プロンプトで指示するのではない。

Hookで確定的にフォーマットを強制する。

Permissionで危険な操作をブロックする。

プロンプトの工夫ではなく、環境の設計でエージェントの品質と安全性を担保する。

👉 ThreadPostでSNS運用を自動化する