コンテキスト予算 は何をしますか？
Claude Code セッション内のすべてのロード済みコンポーネントにおけるトークンオーバーヘッドを分析し、コンテキスト領域を再利用するための実用的な最適化を提示します。
使用するタイミング
- セッションのパフォーマンスが低下したり、出力品質が低下している場合
- 最近、多数のスキル、エージェント、または MCP サーバーを追加した場合
- 実際にどの程度のコンテキストヘッドルームがあるかを把握したい場合
- さらにコンポーネントを追加する予定があり、その余地があるかどうかを確認したい場合
/context-budgetコマンドを実行した場合（このスキルがバックエンドとして機能します）
動作の仕組み
フェーズ 1: インベントリ
すべてのコンポーネントディレクトリをスキャンし、トークン消費量を推定します。
エージェント (agents/*.md)
- ファイルごとの行数とトークン数をカウント（単語数 × 1.3）
- フロントマターの
descriptionの長さを抽出 - フラグ: ファイル >200行（重い）、description >30単語（肥大化したフロントマター）
スキル (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 が30単語を超えると、すべての Task ツール呼び出しに読み込まれます
- 重いエージェント — ファイル >200行は、Task ツールのコンテキストをスパーンごとに膨らませます
- 冗長なコンポーネント — エージェントロジックを複製するスキル、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ツールのサーバーは、すべてのスキルを合わせたよりもコストがかかる
- エージェントの説明文は常にロードされる: エージェントが呼び出されなくても、その description フィールドはすべての Task ツールコンテキストに存在する
- デバッグには詳細モード: 通常の監査ではなく、オーバーヘッドを正確に引き起こしているファイルを特定する必要がある場合に使用する
- 変更後は監査を実行: エージェント、スキル、MCP サーバーを追加した後は必ず実行し、肥大化の早期発見を行う