Problemas e soluções para o recurso de compactação do Claude Code

Mais tarde, criei um plugin que pode incluir automaticamente o seguinte conteúdo e aprimorar de forma transparente o recurso compacto.

https://x.com/u1/status/2073742408555343968

Como o Compact do Claude Code Realmente Funciona

Como premissa, o compact do Claude Code opera por meio de dois caminhos:

• Compact manual (/compact): Acionado explicitamente pelo usuário. Pode ser executado a qualquer momento.
• Compact automático: Executado automaticamente quando o uso do contexto da sessão se aproxima do limite (cerca de 90-95% na prática). Não é executado no momento exato em que o usuário pretende, mas sim nos limites de turno onde você percebe de repente que foi comprimido.

Em ambos os caminhos, o conteúdo é o mesmo: o histórico da conversa anterior é enviado ao LLM para criar um resumo em linguagem natural, e o resumo + turnos recentes + prompt do sistema são reconstruídos como um novo contexto. O resumo se torna uma descrição narrativa do "que foi feito" e, como resultado, a estrutura de decisão — como "por que essa escolha foi feita", "quais planos foram rejeitados" e "em que fase estamos atualmente" — é enfraquecida. Além disso, uma vez que a compressão é executada, é uma operação irreversível; você não pode retornar aos logs brutos anteriores à compressão.

De uma perspectiva de hook, a compressão pode ser capturada pelo evento PostCompact. No entanto, o hook PostCompact não pode retornar additionalContext, portanto, não há caminho para injetar instruções diretamente no agente imediatamente após a compressão. Para inserir instruções, é necessário passar pelo evento UserPromptSubmit subsequente. Essa restrição dita o design do hook neste artigo.

O que Há de Errado com o Compact Padrão

O /compact do Claude Code resume o histórico da conversa, colocando o resultado como o contexto inicial para uma nova sessão. Embora o resumo em si seja razoável, ele é um "registro de trabalho do passado" em vez de uma "instrução para o que fazer a seguir". Consequentemente, o agente pós-compressão se torna propenso aos seguintes equívocos:

• Perder o limite entre "instruções de trabalho" e "registros de trabalho". Se o resumo diz "O Plano A foi considerado", o agente pode começar a implementar o Plano A em vez do Plano B realmente adotado.
• Confundir a fase de verificação com a fase de implementação. A premissa de "verificar na máquina real antes de implantar" desaparece do resumo, e o agente pode pular para operações de implantação destrutivas no próximo turno.
• Repropor abordagens incorretas que já foram descartadas. O resumo pode registrar que uma abordagem foi "tentada", mas não o "motivo pelo qual foi rejeitada".
• Perder o "estado da sessão", como modo de plano, delegação de worker ou árvores de tarefas. O agente pode continuar o trabalho fora do modo de plano ou esquecer a existência de workers em execução no tmux e começar a fazer o trabalho sozinho.

Que Tipo de Acidentes Realmente Ocorreram

Olhando para trás nas minhas sessões da última semana, observei pelo menos quatro padrões imediatamente após um compact. Todos parecem enraizados na falha em separar "instruções de trabalho" de "registros de trabalho":

• Implantação antes da verificação: Apesar de concordar em "verificar o comportamento na máquina antes de colocar os arquivos", o agente viu apenas a imagem de conclusão no resumo após a compressão, pulou a verificação e sobrescreveu o destino.
• Reexecução de atalhos rejeitados: Como o resumo registrou uma abordagem de atalho falha como um "procedimento testado", o agente a reexecutou e caiu na mesma falha novamente.
• Esquecimento dos princípios de design: Princípios estabelecidos durante a sessão, como "editar o repositório de origem em vez do destino", desapareceram do resumo, levando o agente a fazer edições diretas que funcionam a curto prazo, mas não são reproduzíveis.
• Má compreensão dos objetivos da tarefa: O propósito específico de um teste corrigido antes da compressão foi perdido, levando o agente a se desviar para investigações periféricas e começar a trabalhar em uma linha completamente diferente.

Isso ocorreu várias vezes dentro da mesma sessão, com diferentes tipos de equívocos acontecendo após cada compact. Vejo isso como falhas estruturais da especificação padrão do compact, e não como acidentes isolados.

O Que Eu Construí

(1) Habilidade compact-prep

Uma habilidade implementada como um comando de barra que o usuário executa explicitamente antes de digitar /compact. Ela extrai a "estrutura de decisão" e o "estado da sessão" que provavelmente não caberão em um resumo e os salva em um arquivo de estado em um caminho fixo (${TMPDIR}/claude-compact-state/<session_id>.md) em um formato específico.

Os itens salvos incluem aqueles que são difíceis de capturar em resumos:

• Plano Ativo (caminho do arquivo de plano e fase atual)
• Resumo da TaskList (tarefas em andamento e complementos)
• Decisões da Sessão (planos adotados / planos rejeitados / motivos da rejeição)
• Restrições e Bloqueadores
• Topologia dos Workers (painéis tmux-bridge / funções / atribuições)
• Arquivos em Edição (notas sobre alterações não salvas ou não verificadas)
• Notas de Recuperação (uma carta para o eu pós-compressão)

O ponto chave do design é "aplicação mecânica". Ele usa uma barreira rígida para impedir a criação de arquivos se um session_id não for encontrado, uma função de força com cabeçalhos fixos para detectar omissões e ferramentas permitidas restritas para evitar corrupção de estado.

(2) Hook de dois estágios: PostCompact + UserPromptSubmit

Mesmo que (1) escreva um arquivo de estado, não adianta nada se o agente pós-compressão não o ler. Como o PostCompact não pode retornar additionalContext, usei uma configuração de dois estágios:

1. O hook PostCompact escreve um arquivo de marcador com o session_id (sem instruções, apenas registrando que a compressão ocorreu).
2. Quando o próximo hook UserPromptSubmit detecta o marcador, ele injeta instruções via additionalContext: "Leia o arquivo de plano / Leia o arquivo de estado / Verifique a TaskList / Trate os próximos passos do resumo como hipóteses / Confirme o reingresso se o modo de plano foi desativado", e então exclui o marcador.

Como o Claude Code não possui um mecanismo de estado compartilhado entre hooks, um marcador no sistema de arquivos é o único caminho de comunicação. Isso mantém cada hook enxuto com uma única responsabilidade. Em turnos normais, a sobrecarga é apenas uma verificação test -f.

(3) Notificação de 60% (Para evitar o compact automático)

As ferramentas anteriores assumem que o usuário executa manualmente /compact-prep → /compact. No entanto, o compact automático é executado sem aviso, ignorando esse fluxo. Se o compact automático ocorrer primeiro, o arquivo de estado não é salvo e os logs brutos são esmagados em um resumo, perdendo o material de recuperação.

A solução é criar um estado onde o usuário possa executar manualmente o prep antes que o compact automático seja acionado. Este é o propósito da notificação de 60%.

Por que 60%?

• Tempo de antecedência suficiente: O compact automático é acionado por volta de 90-95%. 60% fornece uma margem de 30%, garantindo que o usuário veja o aviso antes que o próximo turno acione um compact automático.
• Espaço para chegar a um ponto de parada: A 60%, ainda há 30% de capacidade restante para concluir uma subtarefa antes de salvar o estado.
• Gatilho mecânico: Atua como uma função de força quando você está muito focado para notar o consumo de contexto.
• Suposição de Contexto de 1M: Com um contexto de 200K, 60% é muito pequeno. Eu uso o contexto de 1M (Opus 4.7), onde 60% deixa cerca de 600K tokens — espaço suficiente para terminar o trabalho e executar o prep.

A implementação envolve um hook statusline escrevendo um marcador de aviso no limite, e um hook UserPromptSubmit detectando-o para sugerir a execução de /compact-prep.

Resultados

As sessões agora estão estáveis mesmo após cerca de 10 compactações sem colapso lógico!

• A perda de trabalho devido à compressão é quase zero.
• Reproposições de ideias rejeitadas desapareceram.
• O modo de plano é mantido.
• Não há mais esquecimento da topologia ao executar vários workers no tmux.

Referência: Código de Implementação

Abaixo estão os códigos reais da habilidade e dos hooks. Eles funcionam copiando-os para o diretório padrão do Claude Code (~/.claude/).

A: Corpo da habilidade compact-prep

Coloque em ~/.claude/skills/compact-prep/SKILL.md.

1---
2name: compact-prep
3description: |
4  Antes de executar /compact no Claude Code, salve o estado atual da sessão em um arquivo de estado temporário.
5  GATILHOS OBRIGATÓRIOS: /compact-prep, compact-prep, preparação para compressão.
6  NÃO GATILHAR: recuperação após compact, relatórios de progresso normais, criação de planos.
7strict_procedure: true
8argument-hint: "[notas de recuperação]"
9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)
10---
11
12# compact-prep
13
14Salva o estado da sessão que é difícil de manter em resumos de compressão em
15`${TMPDIR}/claude-compact-state/${SESSION_ID}.md` antes de `/compact`.
16
17## Perfil de procedimento estrito
18
19- Rigor: procedimento estrito.
20- Barreiras rígidas: Pare se o session_id não puder ser recuperado.
21- Função de força: Caminho fixo e verificação obrigatória de cabeçalhos após salvar.
22- Recibo de conclusão: Relate o caminho do arquivo, itens salvos e orientação para executar `/compact`.
23
24## Procedimento
25
261. Obtenha o session_id via `~/.claude/scripts/get-session-id.sh`.
272. Defina o caminho para `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md`.
283. Verifique a TaskList, o plano ativo, o tmux-bridge e os arquivos em edição.
294. Salve os cabeçalhos na ordem: # Compact Prep State, ## Active Plan, ## Current Phase, ## TaskList Summary, ## Session Decisions, ## Constraints and Blockers, ## Worker Topology, ## Editing Files, ## Recovery Notes.
305. Verifique se todos os cabeçalhos existem.
316. Informe ao usuário: "Preparação concluída. Por favor, execute `/compact`."

B: Hooks de recuperação (2 estágios)

B-1: Hook PostCompact

~/.claude/hooks/compaction-recovery.sh

B-2: Hook UserPromptSubmit (Injeção)

~/.claude/hooks/userpromptsubmit-compaction-recovery.sh

C: Notificação de 60%

C-1: Ramo de limite do hook statusline

Adicionado a ~/.claude/hooks/statusline.sh.

C-2: Hook UserPromptSubmit (Lembrete)

~/.claude/hooks/userpromptsubmit-compact-prep-reminder.sh

D: Registro em settings.json

Adicione os hooks a ~/.claude/settings.json.