context-budget

Context Budget

分析 Claude Code 工作階段中每個已載入元件的 Token 開銷，並提出可操作的優化建議以回收上下文空間。

使用時機

• 工作階段效能感覺遲緩或輸出品質下降
• 你最近新增了許多技能、代理或 MCP 伺服器
• 你想知道實際上還有多少上下文空間
• 打算新增更多元件，需要確認是否還有空間
• 執行 /context-budget 指令（此技能為其後端）

運作方式

階段 1：盤點

掃描所有元件目錄並估算 Token 消耗量：

代理（agents/*.md）

• 計算每個檔案的列數與 Token 數（words × 1.3）
• 擷取 description frontmatter 長度
• 標記：檔案 >200 列（過重）、description >30 字（frontmatter 臃腫）

技能（skills/*/SKILL.md）

• 計算每個 SKILL.md 的 Token 數
• 標記：檔案 >400 列
• 檢查 .agents/skills/ 中是否有重複副本 — 跳過相同副本以避免重複計算

規則（rules/**/*.md）

• 計算每個檔案的 Token 數
• 標記：檔案 >100 列
• 偵測相同語言模組中規則檔案之間的內容重疊

MCP 伺服器（.mcp.json 或作用中的 MCP 設定）

• 計算設定的伺服器數量與工具總數
• 以每個工具約 500 Token 估算 Schema 開銷
• 標記：工具數 >20 的伺服器、包裝簡單 CLI 指令（gh、git、npm、supabase、vercel）的伺服器

CLAUDE.md（專案層級 + 使用者層級）

• 計算 CLAUDE.md 鏈中每個檔案的 Token 數
• 標記：合計總列數 >300 列

階段 2：分類

將每個元件歸入一個類別：

類別	條件	動作
總是需要	在 CLAUDE.md 中被引用、支援作用中的指令、或符合當前專案類型	保留
有時需要	領域特定（例如語言模式）、未在 CLAUDE.md 中被引用	考慮按需啟用
很少需要	無指令引用、內容重疊、或無明顯專案匹配	移除或延遲載入

階段 3：偵測問題

識別以下問題模式：

• 臃腫的代理描述 — frontmatter 中 description >30 字，每次 Task 工具呼叫都會載入
• 過重的代理 — 檔案 >200 列，每次生成時都會膨脹 Task 工具上下文
• 重複元件 — 技能重複代理邏輯、規則重複 CLAUDE.md
• MCP 過度訂閱 — 伺服器 >10 個，或包裝了可免費使用的 CLI 工具
• CLAUDE.md 臃腫 — 冗長說明、過時章節、應改為規則的指示

階段 4：報告

產出上下文預算報告：

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

總估計開銷：~XX,XXX Token
上下文模型：Claude Sonnet（200K 視窗）
有效可用上下文：~XXX,XXX Token（XX%）

元件細項：
┌─────────────────┬────────┬───────────┐
│ 元件            │ 數量   │ Token     │
├─────────────────┼────────┼───────────┤
│ 代理            │ N      │ ~X,XXX    │
│ 技能            │ N      │ ~X,XXX    │
│ 規則            │ N      │ ~X,XXX    │
│ MCP 工具        │ N      │ ~XX,XXX   │
│ CLAUDE.md       │ N      │ ~X,XXX    │
└─────────────────┴────────┴───────────┘

警告：發現 N 個問題：
[依 Token 節省量排序]

前 3 大優化：
1. [動作] → 節省 ~X,XXX Token
2. [動作] → 節省 ~X,XXX Token
3. [動作] → 節省 ~X,XXX Token

潛在節省量：~XX,XXX Token（目前開銷的 XX%）

在詳細模式下，額外輸出每個檔案的 Token 數、最重檔案的逐行細項、重疊元件之間的特定重複行、以及 MCP 工具清單（含每個工具的 Schema 大小估算）。

範例

基本稽核

使用者：/context-budget
技能：掃描設定 → 16 個代理（12,400 Token）、28 個技能（6,200）、87 個 MCP 工具（43,500）、2 個 CLAUDE.md（1,200）
       標記：3 個過重代理、14 個 MCP 伺服器（3 個可被 CLI 取代）
       最大節省：移除 3 個 MCP 伺服器 → -27,500 Token（開銷減少 47%）

詳細模式

使用者：/context-budget --verbose
技能：完整報告 + 逐檔案細項，顯示 planner.md（213 列、1,840 Token）、
       MCP 工具清單（含每個工具大小）、重複規則行並列顯示

擴充前檢查

使用者：我想新增 5 個 MCP 伺服器，還有空間嗎？
技能：目前開銷 33% → 新增 5 個伺服器（約 50 個工具）將增加約 25,000 Token → 開銷推升至 45%
       建議：先移除 2 個可被 CLI 取代的伺服器，以維持開銷低於 40%

最佳做法

• Token 估算：散文使用 words × 1.3，程式碼密集檔案使用 chars / 4
• MCP 是最大的槓桿：每個工具 Schema 約耗費 500 Token；一個 30 工具的伺服器比所有技能加起來還貴
• 代理描述總是載入：即使代理從未被呼叫，其 description 欄位仍存在於每次 Task 工具上下文中
• 詳細模式用於除錯：當你需要精確找出造成開銷的檔案時使用，而非例行稽核
• 變更後稽核：新增任何代理、技能或 MCP 伺服器後執行，以早期發現膨脹