context-budget

Context Budget

分析 Claude Code 会话中每个已加载组件的 Token 开销，并给出切实可行的优化方案，帮你省出宝贵的上下文空间。

使用场景

• 会话响应变迟钝，或输出质量明显下降时
• 最近新增了大量 Skill、Agent 或 MCP 服务
• 想清楚了解当前到底还有多少上下文余量（headroom）
• 打算添加更多组件，需要确认空间是否足够
• 执行 /context-budget 命令时（本 Skill 即为其底层支撑）

工作原理

阶段 1：资产盘点 (Inventory)

扫描所有组件目录并估算 Token 消耗：

Agents (agents/*.md)

• 统计每个文件的行数与 Token 数（词数 × 1.3）
• 提取 frontmatter 中 description 的长度
• 预警规则：文件 >200 行（属于重型组件），或 description >30 个词（frontmatter 臃肿）

Skills (skills/*/SKILL.md)

• 统计每个 SKILL.md 的 Token 数
• 预警规则：文件 >400 行
• 检查 .agents/skills/ 中的重复副本 — 跳过完全相同的副本以避免重复计算

Rules (rules/**/*.md)

• 统计每个文件的 Token 数
• 预警规则：文件 >100 行
• 检测同语言模块内 Rule 文件之间的内容重叠

MCP Servers (.mcp.json 或当前生效的 MCP 配置)

• 统计已配置的服务器数量与工具（tool）总数
• 估算 schema 开销：每个 tool 约占 ~500 tokens
• 预警规则：单服务器包含 >20 个 tool，或服务器封装了本就可以直接用 CLI 命令替代的工具（如 gh、git、npm、supabase、vercel）

CLAUDE.md（项目级 + 用户级）

• 统计 CLAUDE.md 调用链中每个文件的 Token 数
• 预警规则：合并总计 >300 行

阶段 2：组件分类 (Classify)

将所有组件归入以下分类：

分类	划分标准	处理建议
必须保留 (Always needed)	被 CLAUDE.md 引用、支撑某项活跃命令，或契合当前项目类型	保持现状
按需保留 (Sometimes needed)	特定领域专属（如特定语言的代码范式），未被 CLAUDE.md 引用	考虑按需激活
很少使用 (Rarely needed)	无命令引用、内容重叠，或与当前项目无明显关联	移除或改为按需加载 (lazy-load)

阶段 3：问题诊断 (Detect Issues)

排查以下常见问题模式：

• Agent 描述过长 — frontmatter 中的 description 超过 30 个词，每次调用 Task 工具都会一并加载
• 重型 Agent (Heavy agents) — 文件 >200 行，每次衍生 (spawn) 都会膨胀 Task 工具的上下文
• 冗余组件 — Skill 重复了 Agent 的逻辑，或 Rule 重复了 CLAUDE.md 的内容
• MCP 服务超配 — 配置了 >10 个服务器，或封装了系统已有的免费 CLI 工具
• CLAUDE.md 臃肿 — 存在冗长的解释说明、过时的章节，或者本应拆分为 Rule 的指令

阶段 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):
[ranked by token savings]

Top 3 Optimizations:
1. [action] → save ~X,XXX tokens
2. [action] → save ~X,XXX tokens
3. [action] → save ~X,XXX tokens

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

在详细模式（verbose mode）下，还会额外输出：单文件 Token 统计、最臃肿文件的逐行剖析、重叠组件间具体的重复行对比，以及包含每个 tool schema 预测大小的 MCP 工具列表。

示例

基础审计

User: /context-budget
Skill: 扫描当前配置 → 16 个 Agent (12,400 tokens)，28 个 Skill (6,200)，87 个 MCP tool (43,500)，2 个 CLAUDE.md (1,200)
       命中预警：3 个重型 Agent，14 个 MCP 服务器（其中 3 个可替换为 CLI）
       最高收益建议：移除 3 个 MCP 服务器 → 节省 27,500 个 token（降低 47% 的开销）

详细模式

User: /context-budget --verbose
Skill: 输出完整报告 + 单文件开销明细（显示 planner.md 为 213 行、1,840 tokens）、
       带单个 tool 体积的 MCP 工具列表、重叠规则行并排对比

扩展前容量评估

User: 我想再加 5 个 MCP 服务器，空间还够吗？
Skill: 当前开销 33% → 增加 5 个服务器（约 50 个 tool）将新增 ~25,000 tokens → 总开销推高至 45%
       建议：先移除 2 个可被 CLI 替代的服务器，确保开销控制在 40% 以下

最佳实践

• Token 估算：对于普通文本，按 词数 × 1.3 计算；对于代码密集型文件，按 字符数 / 4 计算
• MCP 是最大的优化抓手：每个工具的 schema 大概消耗 ~500 个 token；一个包含 30 个 tool 的 MCP 服务器，比你所有 Skill 加起来还要大
• Agent 描述始终会被加载：即便某个 Agent 从未被显式调用，它的 description 也会出现在每次 Task 工具的上下文中
• 详细模式适合定向排查：当需要精准定位造成高开销的具体文件时使用，不适合日常常规审计
• 变更后及时复查：每次新增 Agent、Skill 或 MCP 服务器后都运行一次，及早发现膨胀苗头