Context Budget
Analise a sobrecarga de tokens em cada componente carregado em uma sessão do Claude Code e descubra otimizações acionáveis para recuperar espaço de contexto.
Quando Usar
- O desempenho da sessão parece lento ou a qualidade da saída está degradando
- Você adicionou recentemente muitas skills, agentes ou servidores MCP
- Você quer saber quanta margem de contexto realmente tem
- Planeja adicionar mais componentes e precisa saber se há espaço
- Executando o comando
/context-budget(esta skill o implementa)
Como Funciona
Fase 1: Inventário
Varre todos os diretórios de componentes e estima o consumo de tokens:
Agentes (agents/*.md)
- Conta linhas e tokens por arquivo (palavras × 1,3)
- Extrai o tamanho da descrição no frontmatter
- Sinaliza: arquivos >200 linhas (pesados), descrição >30 palavras (frontmatter inchado)
Skills (skills/*/SKILL.md)
- Conta tokens por SKILL.md
- Sinaliza: arquivos >400 linhas
- Verifica cópias duplicadas em
.agents/skills/— ignora cópias idênticas para evitar contagem dupla
Regras (rules/**/*.md)
- Conta tokens por arquivo
- Sinaliza: arquivos >100 linhas
- Detecta sobreposição de conteúdo entre arquivos de regras no mesmo módulo de linguagem
Servidores MCP (.mcp.json ou configuração MCP ativa)
- Conta servidores configurados e total de ferramentas
- Estima sobrecarga de schema em ~500 tokens por ferramenta
- Sinaliza: servidores com >20 ferramentas, servidores que encapsulam comandos CLI simples (
gh,git,npm,supabase,vercel)
CLAUDE.md (projeto + nível de usuário)
- Conta tokens por arquivo na cadeia de CLAUDE.md
- Sinaliza: total combinado >300 linhas
Fase 2: Classificar
Classifica cada componente em um balde:
| Balde | Critério | Ação |
|---|---|---|
| Sempre necessário | Referenciado em CLAUDE.md, implementa um comando ativo ou corresponde ao tipo de projeto atual | Manter |
| Às vezes necessário | Específico de domínio (ex.: padrões de linguagem), não referenciado em CLAUDE.md | Considerar ativação sob demanda |
| Raramente necessário | Nenhuma referência de comando, conteúdo sobreposto ou sem correspondência óbvia com o projeto | Remover ou carregar sob demanda |
Fase 3: Detectar Problemas
Identifique os seguintes padrões problemáticos:
- Descrições inchadas de agentes — descrição >30 palavras no frontmatter carrega em toda invocação da ferramenta Task
- Agentes pesados — arquivos >200 linhas inflam o contexto da ferramenta Task a cada spawn
- Componentes redundantes — skills que duplicam lógica de agentes, regras que duplicam CLAUDE.md
- Assinatura excessiva de MCP — >10 servidores, ou servidores encapsulando ferramentas CLI disponíveis gratuitamente
- Inchaço do CLAUDE.md — explicações prolixas, seções desatualizadas, instruções que deveriam ser regras
Fase 4: Relatório
Produz o relatório de orçamento de contexto:
Relatório de Orçamento de Contexto
═══════════════════════════════════════
Sobrecarga total estimada: ~XX.XXX tokens
Modelo de contexto: Claude Sonnet (janela de 200K)
Contexto disponível efetivo: ~XXX.XXX tokens (XX%)
Detalhamento de Componentes:
┌─────────────────┬────────┬───────────┐
│ Componente │ Cont. │ Tokens │
├─────────────────┼────────┼───────────┤
│ Agentes │ N │ ~X.XXX │
│ Skills │ N │ ~X.XXX │
│ Regras │ N │ ~X.XXX │
│ Ferramentas MCP │ N │ ~XX.XXX │
│ CLAUDE.md │ N │ ~X.XXX │
└─────────────────┴────────┴───────────┘
AVISO: Problemas Encontrados (N):
[ordenados por economia de tokens]
Top 3 Otimizações:
1. [ação] → economiza ~X.XXX tokens
2. [ação] → economiza ~X.XXX tokens
3. [ação] → economiza ~X.XXX tokens
Economia potencial: ~XX.XXX tokens (XX% da sobrecarga atual)
No modo verbose, adicionalmente exibe contagens de tokens por arquivo, detalhamento linha a linha dos arquivos mais pesados, linhas redundantes específicas entre componentes sobrepostos e lista de ferramentas MCP com estimativas de tamanho de schema por ferramenta.
Exemplos
Auditoria básica
Usuário: /context-budget
Skill: Varre configuração → 16 agentes (12.400 tokens), 28 skills (6.200), 87 ferramentas MCP (43.500), 2 CLAUDE.md (1.200)
Sinaliza: 3 agentes pesados, 14 servidores MCP (3 substituíveis por CLI)
Principal economia: remover 3 servidores MCP → -27.500 tokens (47% de redução de sobrecarga)
Modo verbose
Usuário: /context-budget --verbose
Skill: Relatório completo + detalhamento por arquivo mostrando planner.md (213 linhas, 1.840 tokens),
lista de ferramentas MCP com tamanhos por ferramenta, linhas de regras duplicadas lado a lado
Verificação pré-expansão
Usuário: Quero adicionar mais 5 servidores MCP, tenho espaço?
Skill: Sobrecarga atual 33% → adicionar 5 servidores (~50 ferramentas) adicionaria ~25.000 tokens → sobe para 45% de sobrecarga
Recomendação: remova primeiro 2 servidores substituíveis por CLI para ficar abaixo de 40%
Melhores Práticas
- Estimativa de tokens: use
palavras × 1,3para prosa,caracteres / 4para arquivos com muito código - MCP é a maior alavanca: cada schema de ferramenta custa ~500 tokens; um servidor com 30 ferramentas custa mais que todas as suas skills juntas
- Descrições de agentes são carregadas sempre: mesmo que o agente nunca seja invocado, seu campo de descrição está presente em todo contexto da ferramenta Task
- Modo verbose para depuração: use quando precisar identificar os arquivos exatos que estão causando sobrecarga, não para auditorias regulares
- Auditar após mudanças: execute após adicionar qualquer agente, skill ou servidor MCP para detectar crescimento precocemente