compactação-estratégica

Habilidade de Compactação Estratégica

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 dentro da 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 é acionada em pontos arbitrários:

• Frequentemente no meio da tarefa, perdendo contexto importante
• Sem conhecimento 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 — Compacta contexto de pesquisa, mantém o plano de implementação
• Após concluir um marco — Novo começo 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 é executado no PreToolUse (Editar/Escrever) e combina dois sinais:

1. Tamanho do contexto (principal) — Lê o registro de usage mais recente da transcrição 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 ajustado à 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 relembra a cada 60k tokens adicionais de crescimento de contexto
2. Contagem de chamadas de ferramenta (secundário) — Conta invocações de ferramentas 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 grandes de arquivo ou respostas MCP podem preencher a janela em muito poucas chamadas, enquanto muitas chamadas minúsculas podem ultrapassar 50 com uma janela quase vazia. O sinal de tamanho de contexto dispara quando realmente importa.

Configuração do 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 de tamanho de contexto (padrão: 160000 em janela de 200k, 250000 em 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 que arquivos de estado por sessão obsoletos no diretório temporário sejam 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 relatado 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 dimensionado para a janela real, em vez de usar o padrão de 200k e superestimar o uso do contexto.
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Substituição nativa do tamanho da janela do Claude Code, em tokens; respeitado como fallback quando ECC_CONTEXT_WINDOW_TOKENS não está definido.

A janela de contexto é, de outra forma, 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 sinais, defina uma das substituições acima para que a sugestão /compact seja acionada no ponto certo.

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 mudar o 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 arquivos 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 a compactar com confiança:

Persiste	Perde-se
Instruções 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 de várias 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 de usuário ditas verbalmente

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

O Claude Code 2.1.233 removeu as ferramentas 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 — ela não viaja com esta habilidade, então você não pode assumir que o leitor a possui.

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 estão 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 todas as versões e todos os modelos. Trate a lista de tarefas como uma conveniência que pode estar ausente, nunca como seu registro durável.

Melhores Práticas

1. Compacte após o planejamento — Assim que o plano estiver finalizado e escrito em um arquivo, compacte para começar de novo
2. Compacte após 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 alterações relacionadas
4. Leia a sugestão — O hook informa 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 da Tabela de Gatilho

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

Gatilho	Habilidade	Carregar Quando
"test", "tdd", "cobertura"	fluxo-tdd	Usuário menciona teste
"segurança", "auth", "xss"	revisão-segurança	Trabalho relacionado a segurança
"deploy", "ci/cd"	padrões-implantação	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 enxutos
• Habilidades carregadas — Cada habilidade adiciona 1-5K tokens
• Histórico da conversa — Cresce a cada troca
• Resultados de ferramentas — Leituras de arquivos, resultados de busca adicionam volume

Detecção de Instruções Duplicadas

Fontes comuns de contexto duplicado:

• Mesmas regras tanto em ~/.claude/rules/ quanto no projeto .claude/rules/
• Habilidades que repetem instruções do CLAUDE.md
• Várias habilidades cobrindo domínios sobrepostos

Ferramentas de Otimização de Contexto

• token-optimizer MCP — Redução automática de 95%+ de tokens via desduplicaçã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