context-budget

Audita o peso de contexto carregado na sessão — CLAUDE.md, agents, MCP descriptions, rules ativas, skills invocadas e histórico acumulado. Estima tokens por componente, reporta headroom disponível e emite alertas de overflow. Distinto do cost-tracker (skill 30) que rastreia tokens gastos em completions runtime. Trigger em: "contexto inchado", "context overflow", "quanto contexto estou usando", "peso do contexto", "context budget", "tokens carregados", "sessao lenta", "respostas degradadas", "headroom de contexto", "custo fixo de contexto", "overhead de rules", "overhead dos agents", "impacto do MCP no contexto", "espaco no context window", "quanto cabe no context window"

Quality

94%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Skill 49 — Context Budget

Objetivo

Auditar o peso de contexto carregado em uma sessão Claude Code: quais skills/agents/MCP/rules/CLAUDE.md estão contribuindo para o overhead de tokens, quanto custa cada componente, e o que pode ser cortado ou adiado sem perder funcionalidade.

Distinção crítica:

Skill 30 (cost-tracker) → rastreia tokens/$ gastos em runtime (completions, tool calls)
Skill 49 (context-budget) → audita tokens carregados no contexto antes de qualquer completion (system prompt, CLAUDE.md, rules, skills, MCP descriptions)

Quando usar

Sessão com latência alta ou model degradation (possível context overflow)
Repo novo com .bot/ — auditoria do que foi instalado
Antes de habilitar novo MCP server ou subagent
Após instalar rules system path-scoped — verificar overhead real
Quando /savings mostrar contexto inchado

Protocolo

Fase 0 — Identificar componentes carregados

Listar o que está no contexto da sessão:

1. CLAUDE.md (global + projeto)
2. .claude/rules/**/*.md (path-scoped — quais foram ativados?)
3. skills/ carregadas via Skill() nesta sessão
4. agents/ descrições (sempre presentes no system prompt)
5. MCP server descriptions (presentes para cada server ativo)
6. Arquivos abertos/lidos na sessão
7. Histórico de conversa acumulado

Fase 1 — Estimar peso por componente

Para cada componente, estimar tokens:

regra geral: ~4 chars por token (aproximação BPE)

- ler tamanho do arquivo em bytes
- tokens ≈ bytes / 4
- overhead real pode ser 10-20% maior (BPE não é linear)

Comando de varredura rápida:

# Peso dos arquivos de contexto fixo
find . -name "CLAUDE.md" -o -name "GLOBAL.md" | xargs wc -c 2>/dev/null

# Peso das rules ativas
find .claude/rules/ -name "*.md" | xargs wc -c 2>/dev/null

# Peso dos agents (sempre no system prompt)
find agents/ -name "*.md" | xargs wc -c 2>/dev/null

# Peso das skills (sob demanda — verificar quais foram invocadas)
find skills/ -name "SKILL.md" | xargs wc -c 2>/dev/null | tail -1

Fase 2 — Categorizar por urgência

Categoria	Critério	Ação
Sempre presente	CLAUDE.md, GLOBAL.md, agents/*.md, MCP descriptions	Auditar tamanho, propor corte
Sob demanda	skills/ via Skill()	Verificar se foi invocada sem necessidade
Path-scoped	.claude/rules/*.md	Verificar se paths: glob está restrito
Histórico	Conversa acumulada	Considerar `/clear` ou nova sessão

Fase 3 — Relatório de budget

Output padrão:

## Context Budget — [repo] — [data]

### Componentes fixos (sempre carregados)
| Componente          | Arquivo              | Tokens est. | % budget |
|---------------------|---------------------|-------------|----------|
| CLAUDE.md (global)  | ~/.claude/CLAUDE.md  | ~2.400      | 12%      |
| CLAUDE.md (projeto) | ./CLAUDE.md          | ~800        | 4%       |
| GLOBAL.md           | ./GLOBAL.md          | ~1.200      | 6%       |
| agents/ (16 agents) | agents/*.md          | ~8.000      | 40%      |
| MCP descriptions    | (runtime)            | ~2.000      | 10%      |
| **Subtotal fixo**   |                      | **~14.400** | **72%**  |

### Componentes dinâmicos (esta sessão)
| Componente           | Tokens est. | Necessário? |
|----------------------|-------------|-------------|
| rules/common/*.md    | ~3.200      | ✓ se editando código |
| rules/typescript/*.md| ~800        | ✓ se arquivo .ts ativo |
| skill 09-orchestrator| ~1.200      | ✓ foi invocada |
| skill 11-reviewer    | ~900        | ? verificar |
| histórico conversa   | ~4.000      | — acumula   |
| **Subtotal dinâmico**| **~10.100** | —           |

### Resumo
- **Total estimado:** ~24.500 tokens (~98 KB)
- **Budget disponível (claude-sonnet-4.5):** 200.000 tokens
- **Headroom:** ~175.500 tokens (88%)
- **Status:** ✅ Saudável

### Recomendações
1. `agents/*.md` representa 40% do budget fixo — considerar frontmatter description mais curto
2. `rules/common/` sempre presente — OK para repo de código
3. Histórico acumula ~500 tokens/turno — considerar `/clear` a cada 50 turnos

Fase 4 — Alertas de overflow

Thresholds por modelo:

Modelo	Context window	Alerta (80%)	Crítico (95%)
claude-haiku-3.5	200k tokens	160k	190k
claude-sonnet-4.5	200k tokens	160k	190k
claude-opus-4.5	200k tokens	160k	190k

Sinais de overflow iminente:

Respostas ficam genéricas ou "esquecem" instruções anteriores
Tool calls começam a falhar com erros estranhos
/savings mostra context_tokens subindo exponencialmente

Ações corretivas:

1. /clear — descarta histórico (mantém system prompt)
2. Nova sessão — fresh start completo
3. Remover MCP servers não usados (claude mcp remove <name>)
4. Encurtar agents/*.md descriptions
5. Revisar .claude/rules/ — paths: glob muito amplo?

Checkpoint: aplicar a ação mais barata primeiro (1 ou 2, reversível e imediata) → medir de novo (Fase 1) → se o sintoma persistir, aplicar a próxima ação da lista. Não pular direto pra remover MCP server ou editar agents/*.md sem confirmar que o /clear sozinho não resolveu — são mudanças mais permanentes pra um sintoma que às vezes é só histórico acumulado.

Integração com kit

Invocar após /savings quando contexto parecer inchado
Invocar antes de habilitar novo MCP server
Usar em conjunto com skill 30 (cost-tracker) para visão completa: custo fixo (contexto) + custo variável (completions)
Output de Fase 3 pode ser salvo em memory/context-budget-YYYY-MM-DD.md

Exemplo de invocação

Skill({ skill: "dev-team-kit-fv:49-context-budget" })
// Carrega playbook; agente executa Fases 0-3 e reporta

Ou via comando:

/context-budget

Repository: felvieira/claude-skills-fv
Path: skills/49-context-budget/SKILL.md
Commit: 131fcad

Last updated: 7 days ago
First committed: 29 days ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.