context-budget

name	context-budget
description	Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations.
origin	ECC

Context Budget

Claude Code セッションで読み込まれたすべてのコンポーネントのトークンオーバーヘッドを分析し、コンテキストスペースを回収するための実行可能な最適化を提示します。

使用タイミング

• セッションのパフォーマンスが遅く感じられる場合や出力品質が低下している場合
• 最近多くのスキル、エージェント、または MCP サーバーを追加した場合
• 実際に利用可能なコンテキストの余裕がどれくらいあるか知りたい場合
• さらにコンポーネントを追加する予定があり、余裕があるか確認したい場合
• /context-budget コマンドを実行する場合（このスキルがバックエンドです）

仕組み

フェーズ 1: Inventory

すべてのコンポーネントディレクトリをスキャンし、トークン消費量を推定します：

Agents (agents/*.md)

• ファイルごとの行数とトークン数をカウント（単語数 × 1.3）
• description frontmatter の長さを抽出
• フラグ：200行超のファイル（重量）、30語超の description（肥大化した frontmatter）

Skills (skills/*/SKILL.md)

• SKILL.md ごとのトークン数をカウント
• フラグ：400行超のファイル
• .agents/skills/ 内の重複コピーをチェック — 同一のコピーはスキップして二重カウントを回避

Rules (rules/**/*.md)

• ファイルごとのトークン数をカウント
• フラグ：100行超のファイル
• 同じ言語モジュール内のルールファイル間のコンテンツ重複を検出

MCP Servers (.mcp.json またはアクティブな MCP 設定)

• 設定済みサーバー数とツール総数をカウント
• ツールあたり約500トークンのスキーマオーバーヘッドを推定
• フラグ：20個超のツールを持つサーバー、シンプルな CLI コマンド（gh、git、npm、supabase、vercel）をラップするサーバー

CLAUDE.md（プロジェクトレベル + ユーザーレベル）

• CLAUDE.md チェーン内のファイルごとのトークン数をカウント
• フラグ：合計300行超

フェーズ 2: Classify

すべてのコンポーネントをバケットに分類します：

バケット	基準	アクション
常に必要	CLAUDE.md で参照されている、アクティブなコマンドをバックアップしている、または現在のプロジェクトタイプに一致	保持
時々必要	ドメイン固有（例：言語パターン）、CLAUDE.md で参照されていない	オンデマンドのアクティベーションを検討
まれに必要	コマンド参照なし、コンテンツの重複、またはプロジェクトとの明確な一致なし	削除またはレイジーロード

フェーズ 3: Detect Issues

以下の問題パターンを特定します：

• 肥大化したエージェント description — frontmatter の description が30語超の場合、すべての Task ツール呼び出しに読み込まれます
• 重量級エージェント — 200行超のファイルは、スポーンのたびに Task ツールコンテキストを膨張させます
• 冗長なコンポーネント — エージェントロジックを複製するスキル、CLAUDE.md を複製するルール
• MCP の過剰サブスクリプション — 10個超のサーバー、または無料で利用可能な CLI ツールをラップするサーバー
• CLAUDE.md の肥大化 — 冗長な説明、古いセクション、ルールであるべき指示

フェーズ 4: Report

コンテキストバジェットレポートを生成します：

Context Budget Report
═══════════════════════════════════════

Total estimated overhead: ~XX,XXX tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~XXX,XXX tokens (XX%)

Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component       │ Count  │ Tokens    │
├─────────────────┼────────┼───────────┤
│ Agents          │ N      │ ~X,XXX    │
│ Skills          │ N      │ ~X,XXX    │
│ Rules           │ N      │ ~X,XXX    │
│ MCP tools       │ N      │ ~XX,XXX   │
│ CLAUDE.md       │ N      │ ~X,XXX    │
└─────────────────┴────────┴───────────┘

WARNING: Issues Found (N):
[トークン削減量順にランク付け]

Top 3 Optimizations:
1. [アクション] → 約X,XXXトークン削減
2. [アクション] → 約X,XXXトークン削減
3. [アクション] → 約X,XXXトークン削減

Potential savings: ~XX,XXX tokens (XX% of current overhead)

verbose モードでは、さらにファイルごとのトークン数、最も重いファイルの行ごとの内訳、重複コンポーネント間の具体的な冗長行、ツールごとのスキーマサイズ推定を含む MCP ツールリストも出力します。

例

基本的な監査

User: /context-budget
Skill: セットアップをスキャン → 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%削減）

verbose モード

User: /context-budget --verbose
Skill: 完全なレポート + ファイルごとの内訳（planner.md 213行、1,840トークン）、
       ツールごとのサイズを含む MCPツールリスト、重複するルール行の並列表示

拡張前のチェック

User: MCPサーバーを5つ追加したいのですが、余裕はありますか？
Skill: 現在のオーバーヘッド33% → 5サーバー追加（約50ツール）で約25,000トークン追加 → 45%に到達
       推奨：40%以下に収めるため、まず CLI 代替可能な2サーバーを削除

ベストプラクティス

• トークン推定：散文には 単語数 × 1.3、コードが多いファイルには 文字数 / 4 を使用します
• MCP が最大のレバー：各ツールスキーマは約500トークンかかります。30ツールのサーバーは、すべてのスキルを合わせたよりもコストがかかります
• エージェントの description は常に読み込まれる：エージェントが呼び出されなくても、その description フィールドはすべての Task ツールコンテキストに存在します
• verbose モードはデバッグ用：オーバーヘッドの原因となる正確なファイルを特定する必要がある場合に使用し、通常の監査には使用しないでください
• 変更後に監査：エージェント、スキル、または MCP サーバーを追加した後に実行し、早期にクリープを検出してください