コンテキスト予算 (Context Budget)
Claude Code セッション内のすべての読み込まれているコンポーネントにおけるトークンのオーバーヘッドを分析し、コンテキスト領域を回復するための実行可能な最適化を明らかにします。
使用するタイミング
- セッションのパフォーマンスが低下している、または出力品質が劣化している場合
- 最近多くのスキル、エージェント、またはMCPサーバーを追加した場合
- 実際にどの程度のコンテキストの空き容量があるかを把握したい場合
- さらにコンポーネントを追加する予定があり、追加可能かどうかを確認したい場合
/context-budgetコマンドを実行する場合（このスキルがバックエンドとして機能します）
仕組み
フェーズ1: インベントリ
すべてのコンポーネントディレクトリをスキャンし、トークン消費量を推定します。
エージェント (agents/*.md)
- ファイルごとに行数とトークン数をカウント（単語数 × 1.3）
- フロントマターの
descriptionの長さを抽出 - フラグ: 200行超のファイル（重い）、30語超のdescription（肥大化したフロントマター）
スキル (skills/*/SKILL.md)
- SKILL.mdごとにトークン数をカウント
- フラグ: 400行超のファイル
.agents/skills/内の重複コピーをチェック — 同一コピーは二重カウントを避けるためスキップ
ルール (rules/**/*.md)
- ファイルごとにトークン数をカウント
- フラグ: 100行超のファイル
- 同じ言語モジュール内のルールファイル間でコンテンツの重複を検出
MCPサーバー (.mcp.json またはアクティブなMCP設定)
- 設定されたサーバー数とツール総数をカウント
- スキーマのオーバーヘッドをツールあたり約500トークンと推定
- フラグ: 20個超のツールを持つサーバー、シンプルなCLIコマンド（
gh,git,npm,supabase,vercel）をラップしているサーバー
CLAUDE.md（プロジェクトレベル + ユーザーレベル）
- CLAUDE.md チェーン内のファイルごとにトークン数をカウント
- フラグ: 合計300行超
フェーズ2: 分類
すべてのコンポーネントを以下のバケットに分類します。
| バケット | 基準 | アクション |
|---|---|---|
| 常に必要 | CLAUDE.md で参照されている、アクティブなコマンドをバックアップしている、または現在のプロジェクトタイプに一致する | 維持 |
| 時々必要 | ドメイン固有（例: 言語パターン）、CLAUDE.md で参照されていない | オンデマンドでの有効化を検討 |
| ほとんど不要 | コマンド参照なし、コンテンツの重複あり、またはプロジェクトとの明確な関連性なし | 削除または遅延読み込み |
フェーズ3: 問題の検出
以下の問題パターンを特定します。
- 肥大化したエージェントdescription — フロントマターのdescriptionが30語超で、Taskツールの呼び出しごとに読み込まれる
- 重いエージェント — ファイルが200行超で、タスクツールのコンテキストを毎回膨張させる
- 冗長なコンポーネント — エージェントのロジックを複製するスキル、CLAUDE.md を複製するルール
- MCPの過剰購読 — 10サーバー超、または無料で利用可能なCLIツールをラップしたサーバー
- CLAUDE.md の肥大化 — 冗長な説明、古いセクション、ルールであるべき指示
フェーズ4: レポート
コンテキスト予算レポートを生成します。
コンテキスト予算レポート
═══════════════════════════════════════
推定総オーバーヘッド: ~XX,XXX トークン
コンテキストモデル: Claude Sonnet (200K ウィンドウ)
有効利用可能コンテキスト: ~XXX,XXX トークン (XX%)
コンポーネント内訳:
┌─────────────────┬────────┬───────────┐
│ コンポーネント │ 数 │ トークン │
├─────────────────┼────────┼───────────┤
│ エージェント │ N │ ~X,XXX │
│ スキル │ N │ ~X,XXX │
│ ルール │ N │ ~X,XXX │
│ MCPツール │ N │ ~XX,XXX │
│ CLAUDE.md │ N │ ~X,XXX │
└─────────────────┴────────┴───────────┘
警告: 検出された問題 (N 件):
[トークン節約量でランク付け]
上位3つの最適化案:
1. [アクション] → 約 ~X,XXX トークン節約
2. [アクション] → 約 ~X,XXX トークン節約
3. [アクション] → 約 ~X,XXX トークン節約
節約の可能性: ~XX,XXX トークン (現在のオーバーヘッドの XX%)
詳細モードでは、さらにファイルごとのトークン数、最も重いファイルの行ごとの内訳、重複するコンポーネント間の特定の冗長行、およびツールごとのスキーマサイズ推定を含むMCPツールリストを出力します。
例
基本監査
ユーザー: /context-budget
スキル: 設定をスキャン → 16エージェント (12,400 トークン), 28スキル (6,200), 87 MCPツール (43,500), 2 CLAUDE.md (1,200)
フラグ: 3つの重いエージェント、14のMCPサーバー (うち3つはCLIで代替可能)
最大の節約: 3つのMCPサーバーを削除 → -27,500 トークン (オーバーヘッドの47%削減)
詳細モード
ユーザー: /context-budget --verbose
スキル: 完全レポート + ファイルごとの内訳: planner.md (213行, 1,840トークン)、
MCPツールリスト（ツールごとのサイズ）、重複ルール行の並列表示
追加前の空き容量確認
ユーザー: MCPサーバーをさらに5つ追加したいのですが、空き容量はありますか？
スキル: 現在のオーバーヘッド33% → 5サーバー追加（約50ツール）で約25,000トークン増加 → オーバーヘッド45%に
推奨: まずCLIで代替可能なサーバーを2つ削除し、40%未満に抑える
ベストプラクティス
- トークン推定: 散文には
単語数 × 1.3、コード中心のファイルには文字数 / 4を使用 - MCPが最大のレバレッジポイント: 各ツールスキーマは約500トークン。30ツールのサーバー1つで、すべてのスキルを合わせたよりもコストがかかる
- エージェントのdescriptionは常に読み込まれる: エージェントが呼び出されなくても、そのdescriptionフィールドはすべてのTaskツールのコンテキストに存在する
- デバッグには詳細モード: 通常の監査ではなく、オーバーヘッドの原因となっている正確なファイルを特定する必要がある場合に使用
- 変更後は監査を実行: エージェント、スキル、またはMCPサーバーを追加した後は、早期に肥大化を発見するために実行する