compact-estratégico

Habilidade Compact Estratégico

Sugere /compact manual em pontos estratégicos do seu fluxo de trabalho, em vez de depender de compactação automática arbitrária.

Quando Ativar

• Sessões longas que se aproximam dos limites de contexto (200K+ tokens)
• Trabalhando em tarefas multifásicas (pesquisa → planejamento → implementação → teste)
• Alternando entre tarefas não relacionadas na mesma sessão
• Após concluir um marco importante e iniciar um novo trabalho
• Quando as respostas ficam mais lentas ou menos coerentes (pressão de contexto)

Por que Compactação Estratégica?

A compactação automática dispara em pontos arbitrários:

• Frequentemente no meio de uma tarefa, perdendo contexto importante
• Não tem noção dos limites lógicos da tarefa
• Pode interromper operações complexas de múltiplas etapas

A compactação estratégica em limites lógicos:

• Após exploração, antes da execução — Comprime contexto de pesquisa, mantém o plano de implementação
• Após concluir um marco — Recomeço limpo para a próxima fase
• Antes de grandes mudanças de contexto — Limpa contexto de exploração antes de uma tarefa diferente

Como Funciona

O script suggest-compact.js executa no PreToolUse (Edit/Write) e combina dois sinais:

1. Tamanho do contexto (primário) — Lê o registro usage mais recente do transcript da sessão (transcript_path no payload do hook) e soma input_tokens + cache_read_input_tokens + cache_creation_input_tokens (o tamanho real do contexto da rodada). Sugere /compact em um limite escalado pela janela — 160k tokens em uma janela de 200k, 250k em uma janela de 1M (detectado a partir de um marcador de modelo [1m], ou inferido quando os tokens observados já excedem 200k) — e re-lembra a cada 60k tokens adicionais de crescimento de contexto
2. Contagem de chamadas de ferramenta (secundário) — Conta invocações de ferramenta na sessão; sugere em um limite configurável (padrão: 50 chamadas), depois a cada 25 chamadas

A contagem de ferramentas sozinha é um proxy fraco para pressão na janela: algumas leituras de arquivo grandes ou respostas MCP podem encher a janela em poucas chamadas, enquanto muitas chamadas pequenas podem ultrapassar 50 com uma janela quase vazia. O sinal de tamanho de contexto dispara quando realmente importa.

Configuração de Hook

Instalado como plugin? Nenhuma configuração é necessária. O arquivo hooks/hooks.json do plugin já registra suggest-compact.js (id do hook pre:edit-write:suggest-compact, ativo nos perfis de hook standard e strict). Não copie o bloco abaixo para ~/.claude/settings.json — ~/.claude/scripts/ não existe em instalações de plugin, e duplicar um hook de plugin causa execução dupla.

Se instalado manualmente (./install.sh), adicione ao seu ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
      },
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
      }
    ]
  }
}

Configuração

Variáveis de ambiente:

• COMPACT_THRESHOLD — Chamadas de ferramenta antes da primeira sugestão (padrão: 50)
• COMPACT_CONTEXT_THRESHOLD — Tokens de contexto antes da sugestão baseada em tamanho (padrão: 160000 em uma janela de 200k, 250000 em uma janela de 1M; 0 desabilita o sinal de contexto)
• COMPACT_CONTEXT_INTERVAL — Tokens de contexto adicionais antes da sugestão se repetir (padrão: 60000)
• COMPACT_STATE_TTL_DAYS — Dias antes de arquivos de estado por sessão obsoletos no diretório temporário serem limpos (padrão: 14)
• ECC_CONTEXT_WINDOW_TOKENS — Tamanho explícito da janela de contexto, em tokens, substituindo a detecção automática. Defina isso para modelos de janela grande cujo ID reportado não possui um marcador [1m] (por exemplo, Opus 4.x de 400k, ou uma nova família de modelo de janela de 1M) para que o limite seja escalado para a janela real em vez de usar o padrão de 200k e superestimar o uso de contexto.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Substituição nativa do tamanho da janela do Claude Code, em tokens; usado como fallback quando ECC_CONTEXT_WINDOW_TOKENS não está definido.

A janela de contexto é detectada automaticamente a partir de um marcador de modelo [1m] ou inferida quando os tokens observados já excedem 200k. Em um modelo de janela grande que não carrega nenhum dos dois sinais, defina uma das substituições acima para que a sugestão de /compact dispare no ponto correto.

Guia de Decisão de Compactação

Use esta tabela para decidir quando compactar:

Transição de Fase	Compactar?	Por quê?
Pesquisa → Planejamento	Sim	Contexto de pesquisa é volumoso; o plano é a saída destilada
Planejamento → Implementação	Sim	O plano está escrito (um arquivo, ou a lista de tarefas, se você tiver uma); libere contexto para o código
Implementação → Teste	Talvez	Mantenha se os testes referenciarem código recente; compacte se estiver mudando de foco
Depuração → Próximo recurso	Sim	Rastros de depuração poluem o contexto para trabalho não relacionado
Meio da implementação	Não	Perder nomes de variáveis, caminhos de arquivo e estado parcial é custoso
Após uma abordagem falha	Sim	Limpe o raciocínio sem saída antes de tentar uma nova abordagem

O Que Sobrevive à Compactação

Entender o que persiste ajuda você a compactar com confiança:

Persiste	Perde-se
Instruções do CLAUDE.md	Raciocínio e análise intermediários
Arquivos no disco	Conteúdos de arquivo que você leu anteriormente
Arquivos de memória (~/.claude/memory/)	Contexto de conversa em múltiplas etapas
Estado do Git (commits, branches)	Histórico e contagens de chamadas de ferramenta
A lista de tarefas — apenas se você tiver as ferramentas de todo (veja abaixo)	Preferências sutis do usuário declaradas verbalmente

Não confie na lista de tarefas sobreviver — ela pode não existir

O Claude Code 2.1.233 removeu as ferramentas de todo/task por padrão no Opus 4.8, Sonnet 5, Fable 5, Mythos 5 e modelos mais novos (TodoWrite, TaskCreate/Get/Update/List). CLAUDE_CODE_ENABLE_TODO_TOOLS=1 as traz de volta, mas essa é uma configuração de ambiente por máquina — não viaja com esta habilidade, então você não pode assumir que o leitor a tem.

Isso importa porque "minha lista de tarefas sobrevive à compactação" é uma razão pela qual as pessoas compactam em vez de escrever o estado. Se as ferramentas estiverem ausentes, não há lista para sobreviver, e o plano simplesmente desaparece. Escreva o plano em um arquivo antes de compactar — um arquivo persiste em toda versão e em todo modelo. Trate a lista de tarefas como uma conveniência que pode estar faltando, nunca como seu registro durável.

Melhores Práticas

1. Compacte após o planejamento — Depois que o plano for finalizado e escrito em um arquivo, compacte para começar limpo
2. Compacte após a depuração — Limpe o contexto de resolução de erros antes de continuar
3. Não compacte no meio da implementação — Preserve o contexto para mudanças relacionadas
4. Leia a sugestão — O hook te diz quando, você decide se
5. Escreva antes de compactar — Salve contexto importante em arquivos ou memória antes de compactar
6. Use /compact com um resumo — Adicione uma mensagem personalizada: /compact Foco em implementar middleware de autenticação em seguida

Padrões de Otimização de Tokens

Carregamento Preguiçoso de Tabela de Gatilho

Em vez de carregar o conteúdo completo da skill no início da sessão, use uma tabela de gatilho que mapeia palavras-chave para caminhos de skills. As skills carregam apenas quando acionadas, reduzindo o contexto base em 50%+:

Gatilho	Skill	Carregar Quando
"test", "tdd", "coverage"	tdd-workflow	Usuário menciona testes
"security", "auth", "xss"	security-review	Trabalho relacionado a segurança
"deploy", "ci/cd"	deployment-patterns	Contexto de implantação

Consciência de Composição de Contexto

Monitore o que está consumindo sua janela de contexto:

• Arquivos CLAUDE.md — Sempre carregados, mantenha-os enxutos
• Skills carregadas — Cada skill adiciona 1-5K tokens
• Histórico de conversa — Cresce a cada troca
• Resultados de ferramentas — Leituras de arquivo, resultados de pesquisa adicionam volume

Detecção de Instruções Duplicadas

Fontes comuns de contexto duplicado:

• Mesmas regras tanto em ~/.claude/rules/ quanto em .claude/rules/ do projeto
• Skills que repetem instruções do CLAUDE.md
• Múltiplas skills cobrindo domínios sobrepostos

Ferramentas de Otimização de Contexto

• token-optimizer MCP — Redução automatizada de tokens de 95%+ via deduplicação de conteúdo
• context-mode — Virtualização de contexto (315KB para 5.4KB demonstrado)

Relacionados

• The Longform Guide — Seção de otimização de tokens
• Hooks de persistência de memória — Para estado que sobrevive à compactação
• Habilidade continuous-learning — Extrai padrões antes do fim da sessão