跳转至

上下文预算

分析 Claude Code 会话中加载的所有组件的 Token 开销，并显示用于恢复上下文空间的实用优化。

使用时机

  • 会话性能下降或输出质量下降时
  • 添加了许多技能、代理或 MCP 服务器之后
  • 想要确认实际拥有的上下文余量时
  • 计划添加组件，并想确认是否有空间时
  • 运行 /context-budget 命令时（此技能支持该命令）

工作原理

阶段 1：清单

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

代理 (agents/*.md) - 统计每个文件的行数和 Token（单词数 × 1.3） - 提取 description 前置元数据的长度 - 标记：超过 200 行的文件（过重）、超过 30 个单词的 description（膨胀的前置元数据）

技能 (skills/*/SKILL.md) - 统计每个 SKILL.md 的 Token - 标记：超过 400 行的文件 - 检查 .agents/skills/ 中的重复副本 — 为避免重复计数，跳过相同副本

规则 (rules/**/*.md) - 统计每个文件的 Token - 标记：超过 100 行的文件 - 检测同一语言模块内规则文件之间的内容重复

MCP 服务器 (.mcp.json 或活动 MCP 配置) - 统计已配置服务器数量和工具总数 - 估算每个工具的 Schema 开销约为 500 Token - 标记：拥有 20 个以上工具的服务器，以及包装简单 CLI 命令（gh、git、npm、supabase、vercel）的服务器

CLAUDE.md（项目 + 用户级别） - 统计 CLAUDE.md 链中每个文件的 Token - 标记：总计超过 300 行

阶段 2：分类

将所有组件分类到桶中：

类别 标准 操作
始终需要 在 CLAUDE.md 中引用、支持活动命令，或匹配当前项目类型 保留
偶尔需要 领域特定（例如：语言模式），未在 CLAUDE.md 中引用 考虑按需激活
很少需要 无命令引用、内容重复，或无明显项目匹配 删除或延迟加载

阶段 3：问题检测

识别以下问题模式：

  • 膨胀的代理 description — 前置元数据中超过 30 个单词的 description 会在每次 Task 工具调用时加载
  • 过重的代理 — 超过 200 行的文件会在每次生成时膨胀 Task 工具的上下文
  • 冗余组件 — 复制代理逻辑的技能，复制 CLAUDE.md 的规则
  • MCP 过度订阅 — 10 个以上服务器，或包装可免费使用的 CLI 工具的服务器
  • CLAUDE.md 膨胀 — 冗余说明、过时章节、本应成为规则的指令

阶段 4：报告

生成上下文预算报告：

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)

详细模式还会输出每个文件的 Token 数、最重文件的逐行明细、重复组件之间特定的冗余行，以及包含每个工具 Schema 大小估算的 MCP 工具列表。

示例

基本审计 

User: /context-budget
Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
       Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
       Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)

详细模式 

User: /context-budget --verbose
Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
       MCP tool list with per-tool sizes, duplicated rule lines side by side

扩展前检查 

User: I want to add 5 more MCP servers, do I have room?
Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%

最佳实践

  • Token 估算：散文使用 単語数 × 1.3，代码较多的文件使用 文字数 / 4
  • MCP 是最大杠杆：每个工具 Schema 大约消耗 500 Token。拥有 30 个工具的服务器比所有技能加起来消耗更多
  • 代理 description 始终加载：即使代理未被调用，其 description 字段也会存在于所有 Task 工具的上下文中
  • 调试使用详细模式：仅在需要准确识别特定文件正在驱动开销时使用，不要用于常规审计
  • 变更后审计：在添加代理、技能或 MCP 服务器后运行，以尽早捕获开销增长

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC