クラウドコードAPIの料金爆弾を防ぐトークン予算管理スクリプト
1. トークン上限設定による課金の遮断
小規模プロジェクトを動かしていてAPI料金の請求書を見て驚いた経験があるなら、それは予算制限がなかったからだ。エージェントは思っている以上に会話の文脈を長く維持し、不要なファイル内容を繰り返し読み込む。放置すると一日で数十万トークンが消える。~/.claude/settings.jsonファイルを開き、セッションと日々の使用量を直接制限する必要がある。
ユーザーのグローバル設定ファイルにbudgetオブジェクトを追加する方法は次のとおりだ。
- ターミナルを開き、エディタで~/.claude/settings.jsonファイルを開く。
- JSONブロックの内部にsessionLimit値を500000に、dailyLimit値を2000000に入力する。
- warningThresholdを0.75に指定し、autoCompactAtを0.60に設定して保存する。
コンテキスト容量が60パーセントに達すると会話履歴が自動的に圧縮され、不要なトークンの無駄遣いがなくなる。日々の制限に達する前にセッションが遮断されるため、予算超過の心配から解放される。
2. 3回連続エラー時の強制停止ループブレーカーの構築
エージェントが文法エラーやファイルパスの問題で同じフックでつまずいた場合、解決できないまま無限ループに陥る。この状態を放置すると数分でセッションのトークンが枯渇する。プロンプトに注意するよう書き留めておくだけでは意味がない。シェルスクリプトベースのフックシステムを組み合わせて物理的に遮断しなければならない。
同じエラーを3回連続で検知した場合にプロセスを即座に終了するフックスクリプトを作成する。
- プロジェクトディレクトリに.claude/hooks/loop-breaker.shファイルを作成し、実行権限を付与する。
- スクリプト内で一時状態ファイルを参照してエラーカウンターを1ずつ増やし、累積回数が3以上であれば標準エラーを出力して終了コード2を返し、作業を強制中断する。
- .claude/settings.jsonファイルのPostToolUseFailure項目に該当スクリプトのパスを登録し、リアルタイムで監視させる。
この仕組みを導入すれば、エージェントが的外れなコードを無制限に修正し続けてトークンを消費する現象がなくなる。デバッグ地獄で浪費していた時間を節約できる。
3. 作業の性質に応じたモデルルーティングと手動承認区間の分離
すべてのコーディング作業をClaudeに全面的に任せると予算が持たない。単純なフォーマットやボイラープレートの作成は軽量なモデルに任せ、データベースのマイグレーションのように取り返しのつかない作業は開発者が直接承認する必要がある。シェルエイリアスを活用し、タスクの難易度に適した実行環境を構築する。
作業の性質ごとにエージェント委任コマンドを分離する設定は次のとおりだ。
- /.bashrcまたは/.zshrcファイルを開く。
- 単純なドキュメント作成用に
alias cc-quick='claude --model claude-haiku-3-20250307 --token-budget 100000' コマンドを登録する。
- 一般的な機能開発用に
alias cc-dev='claude --model claude-sonnet-4-20250514 --token-budget 500000 --thinking-budget 8000' コマンドを追加し、ターミナルを再起動する。
この方式を適用すれば、単純反復コーディングの90パーセントをエージェントが安全に処理し、100万トークンあたりに完成するPRの割合が目に見えて向上する。不要なAPI費用を確実に半減させる最も現実的な方法だ。