Índice

O /compact do Claude Code não é algo que se aperta por cronômetro. A hora de apertá-lo é uma pausa no trabalho — uma tarefa concluída, a próxima prestes a começar. A documentação oficial diz isso com todas as letras: rode /compact em um ponto de corte natural do trabalho, por exemplo entre tarefas, em vez de esperar o auto-compact disparar no meio de uma tarefa (documentação do Claude Code, "Prompt caching").

Regras como "apertar a cada 30 minutos" ou "apertar quando o contexto passar de 70%" miram no alvo errado. O resto deste artigo explica por quê, mas a versão curta é esta: o custo e a perda de uma compactação são definidos não por quando você apertou, e sim pelo que você jogou fora e se o cache estava quente.

📌 De onde vêm estes dados: cada especificação, número de versão e nome de configuração abaixo foi conferido em 8 de agosto de 2026 na documentação do Claude Code e nas notas de versão (a mais recente naquele momento: v2.1.226, 8 de agosto de 2026). O Claude Code evolui rápido, e a área de compactação ganhou comportamentos novos até em versões recentes (o /autocompact exige a v2.1.221 ou posterior). Confira a sua própria build com claude --version.

1. A resposta curta — aperte na fronteira, não no relógio

Comecemos pela tabela de decisão. Ela existe para você decidir pela situação, e não pelo relógio.

✅ Quando apertar

Você terminou uma tarefa e está prestes a começar uma longa. Não importa que ainda sobre contexto. O objetivo é antecipar a execução automática nos seus próprios termos, para que nada interrompa você no meio da tarefa.

🟡 Quando /clear é a escolha melhor

O próximo trabalho não tem nada a ver com o anterior. Se você nem precisa do resumo, não há razão para pagar por produzi-lo. A documentação é direta: se você quer recomeçar do zero em vez de continuar, o /clear é gratuito.

🔵 Quando /rewind é a escolha melhor

Você quer descartar toda a direção que tomou. Voltar atrás trunca até um ponto que já está em cache, então sai mais barato que uma compactação, que precisa construir um prefixo inteiramente novo.

❌ Quando não apertar

No meio de uma tarefa. Detalhes que você ainda ia usar são achatados dentro de um resumo. Cada compactação feita "por precaução" te compra o trabalho de reler os mesmos arquivos logo em seguida.

Uma única pergunta separa esses quatro casos. Você ainda vai precisar daquilo que está prestes a jogar fora? Nas palavras da própria documentação, a compactação ajuda quando o contexto descartado realmente não é mais necessário. Uma rotina fixa é uma forma de se recusar a fazer esse julgamento, então às vezes acerta e às vezes erra — e as vezes em que erra custam mais do que as vezes em que acerta.

2. A compactação tem três estágios — o que a documentação diz

Antes de perguntar se vale apertar manualmente, você precisa conhecer a maquinaria que roda independentemente de você apertar qualquer coisa. Quando o contexto começa a encher, o Claude Code não salta direto para resumir a conversa. A documentação descreve assim.

"O Claude Code gerencia o contexto automaticamente conforme você se aproxima do limite: primeiro ele descarta saídas antigas de ferramentas e depois, se necessário, resume a conversa. Seus pedidos e trechos de código importantes são preservados, mas instruções detalhadas do início da conversa podem ser perdidas. Coloque as regras permanentes no CLAUDE.md em vez de confiar no histórico da conversa." (How Claude Code works)

Ou seja, há estágios: (1) as saídas antigas de ferramentas são descartadas, (2) a conversa é resumida automaticamente, (3) você aperta /compact.

1. Descarte de saídas de ferramentas

A conversa fica intacta e só os resultados antigos de ferramentas caem. Você não faz nada. Essa camada trabalha antes de a sumarização entrar em cena.

2. Auto-compact

Quando o estágio 1 não basta, a própria conversa é substituída por um resumo. É o mesmo processamento de um /compact manual; a única diferença é o momento em que roda.

3. /compact manual

Seu único papel de verdade é antecipar o estágio 2 para um momento que convém a você. Além disso, você pode dizer o que manter — a outra diferença em relação ao estágio 2.

Aqui está o coração da resposta. Um /compact manual antecipa algo que aconteceria de qualquer jeito. Não é uma alavanca que economiza contexto extra quanto mais vezes você a puxa. Vale apertá-lo só quando escolher o momento você mesmo vale alguma coisa.

⚠️ Uma observação sobre terminologia. Vários textos chamam o estágio 1 de "microcompactação", mas em 8 de agosto de 2026 a documentação oficial não usa esse nome. O que a documentação traz é uma descrição do comportamento — saídas antigas de ferramentas são descartadas primeiro. Se você procurar pelo termo e não encontrar nada oficial, o motivo é esse.

3. O que sobrevive e o que desaparece

O que acontece com as suas regras durante uma compactação depende inteiramente de como elas foram carregadas. A documentação publica uma lista por mecanismo, então aqui está ela, organizada.

Mecanismo Depois da compactação O que isso significa na prática
System prompt e estilo de saída Inalterados Não fazem parte do histórico da conversa
CLAUDE.md na raiz do projeto e regras sem escopo Reinjetados do disco O lugar mais seguro para guardar coisas. É também onde as suas edições finalmente passam a valer (veja a seção 8)
Memória automática Reinjetada do disco Foi feita para persistir entre sessões, então sobreviver a uma compactação é o mínimo
Regras com paths: Perdidas (até que um arquivo correspondente seja lido de novo) Para mantê-las, remova a chave paths: ou mova a regra para o CLAUDE.md da raiz
CLAUDE.md aninhado em subdiretório Perdido (até que um arquivo daquele diretório seja lido de novo) Idem, e é a ausência mais fácil de não perceber
Corpo das skills que você invocou Reinjetado, mas com teto 5.000 tokens por skill e 25.000 no total, descartando as mais antigas primeiro
Hooks Não se aplica Eles rodam como código, não como contexto

Três conclusões práticas saem dessa tabela.

Primeira: se você conta com ser compactado, coloque as regras que não pode perder no CLAUDE.md da raiz do projeto. Esse é o ponto que a documentação repete sem parar. Regras com paths: e arquivos CLAUDE.md aninhados compram conveniência ao preço de cair fora a cada compactação — e nada na tela avisa que elas se foram.

Segunda: o começo do arquivo de uma skill é o que importa. O corte na reinjeção preserva o início do arquivo, então as instruções importantes de um SKILL.md pertencem ao topo. Além disso, as notas oficiais sobre contexto dizem que a lista de skills carregada no início da sessão não é reinjetada depois de um /compact; só as skills que você de fato invocou são retidas.

Terceira: nada anuncia o que foi perdido. É exatamente por isso que o princípio se sustenta: se perder algo doeria, guarde esse algo em um arquivo, não na conversa.

4. O custo não é definido pelo tamanho do contexto

Supor que "um contexto maior torna o /compact mais caro" é natural, e só metade verdade. O que de fato manda no preço é o cache de prompt estar quente ou não. Eis a explicação da documentação.

"Para produzir o resumo, o Claude Code envia uma requisição separada com o mesmo system prompt, as mesmas ferramentas e o mesmo histórico, mais uma instrução de sumarização no final. Enquanto o cache está quente, essa requisição lê o seu prefixo do cache, então ela custa muito menos do que o tamanho do contexto sugeriria, e a maior parte do tempo vai para gerar o resumo. [...] Depois de uma pausa mais longa que a vida útil do cache não há cache algum para ler, então a requisição de sumarização reprocessa todo o histórico como entrada não cacheada. É por isso que o /compact fica mais caro quando você retoma uma sessão antiga." (Prompt caching)

Esse único parágrafo é o argumento mais forte contra rodar a compactação em intervalos fixos.

Apertado no meio da sessão (cache quente)

O prefixo é lido do cache. O que você sente é apenas o tempo de escrever o resumo. Uma compactação aqui é barata.

Apertado depois de uma pausa (cache frio)

Todo o histórico é reprocessado antes de qualquer resumo. O momento mais caro possível para o mesmo comando. "Vou organizar tudo logo de manhã" pode ser a pior jogada.

O turno logo depois de você apertar

O cache é reconstruído a partir de um resumo curto, então essa parte não é pesada. A impressão de que "tudo fica lento depois de uma compactação" costuma vir dos dois casos acima, não daqui.

A vida útil do cache depende de como você se autentica. Em uma assinatura Claude, um TTL de uma hora é solicitado automaticamente; por chave de API ou por um provedor de nuvem, o padrão é cinco minutos (ENABLE_PROMPT_CACHING_1H=1 eleva para uma hora). O que significa que "voltei do almoço, deixa eu rodar o /compact primeiro" é quase garantidamente uma execução fria em chave de API.

O fato de o próprio /compact ser uma requisição grande também é sublinhado na documentação de custos: "o /compact lê a conversa que está resumindo, então compactar um contexto grande é, em si, uma requisição grande. Se você quer recomeçar do zero em vez de continuar, o /clear é gratuito." (Manage costs effectively). Visto também pela lente da economia de tokens, há muitos momentos em que o /clear ganha de um /compact apertado por hábito.

5. /compact, /clear, /rewind e /recap

O /compact não é o único jeito de aliviar o contexto. Confunda comandos que existem para propósitos diferentes e você acaba pagando pelo caro.

Comando Histórico da conversa Cache Quando escolher
/compact [instrução] Substituído por um resumo A camada da conversa é invalidada Você vai continuar, mas já não precisa dos detalhes do histórico
/clear [nome] Esvaziado Reconstruído (sem nenhum custo de sumarização) O próximo trabalho é sem relação. Dê um nome e o /resume traz de volta
/rewind Truncado até um ponto anterior Acerta o cache antigo Você quer a direção inteira fora. O código pode voltar junto
/recap Intocado (ele só mostra um resumo) Mantido como está Você só quer ler "onde estamos até agora"
/context [all] Intocado Mantido Meça antes de apertar qualquer coisa. Uma visão colorida do que está ocupando espaço

Vale lembrar do /recap. Muita gente aperta /compact porque "esta conversa está ficando longa, eu queria um resumo" — e para esse propósito não há necessidade nenhuma de destruir o histórico. Segundo a documentação, o /recap apenas acrescenta um resumo como saída de comando, então o prefixo cacheado continua intacto.

A natureza do /rewind importa tanto quanto. A documentação explica que voltar atrás devolve você ao mesmo conteúdo que foi cacheado naquele ponto, então a requisição seguinte acerta o cache antigo. Quando você foi na direção errada, a resposta certa é /rewind, não /compact — a compactação constrói um prefixo novo, enquanto o rewind só volta a um que já existe. Checkpoints e rewind têm artigo próprio.

6. Você mesmo pode mover a janela do auto-compact

Antes de se torturar decidindo se aperta na mão, vale saber que você pode mover o ponto em que a execução automática dispara. Da v2.1.221 em diante, o comando /autocompact deixa você especificar quão cheio o contexto precisa ficar antes de o auto-compact entrar em ação.

Definir a janela em 500K tokens (salvo nas configurações de usuário, valendo também para sessões futuras)

/autocompact 500k

Voltar ao padrão adequado ao modelo

/autocompact auto

A faixa aceita vai de 100K a 1M tokens. Você pode escrever um número simples como 200000, um valor com sufixo como 500k ou 1M, ou um número nu entre 100 e 1000 como 200 (lido como milhares). A configuração pode chegar de quatro lugares, e a precedência é fixa.

1. Variável de ambiente (a mais alta)

CLAUDE_CODE_AUTO_COMPACT_WINDOW. Enquanto estiver definida, ela sobrepõe o comando, a flag e o arquivo de configuração

2. Flag de inicialização

claude --autocompact 500k. Vale só para aquela execução e não altera as suas configurações salvas

3. O comando

/autocompact. Grava em autoCompactWindow nas suas configurações de usuário

4. Arquivo de configuração

autoCompactWindow. Se a sua organização tiver uma configuração gerenciada acima dela, essa vence

⚠️ A variável de ambiente é a que tem formato diferente. A documentação afirma explicitamente que CLAUDE_CODE_AUTO_COMPACT_WINDOW aceita apenas um inteiro simples, e que um valor como 500k é lido como 500 e limitado ao mínimo de 100K. Escreva do jeito que se escreve no comando e você terá pedido um milésimo do que queria, e depois sido elevado ao mínimo, compactando muito mais vezes.

Há um segundo alerta no mesmo lugar. O used_percentage da status line sempre mede em relação à janela de contexto completa do modelo, então, uma vez definida essa variável, aquela porcentagem deixa de indicar quando a compactação vai disparar. É exatamente aí que o método de "olhar a porcentagem e apertar na mão" desmorona.

O padrão, quando você não define janela nenhuma, também está documentado. Sem nada configurado, a compactação acontece ao atingir o limite de contexto do modelo, com exceções: sessões na nuvem compactam mais cedo, à medida que se aproximam do limite; Sonnet 4.6 e Opus 4.6 sem contexto estendido compactam na fronteira de 200K; Opus 4.8 e Opus 5 rodando com 200K de contexto no Amazon Bedrock, no Agent Platform do Google Cloud ou no Microsoft Foundry se comportam da mesma forma; e o Sonnet 5 dispara no limiar padrão daquele modelo.

Você também pode desligar o auto-compact por completo, pela configuração autoCompactEnabled (padrão true, exibida como "Auto-compact" no /config) ou pela variável de ambiente DISABLE_AUTO_COMPACT. Não é recomendado. Desligar não encolhe nada; o contexto simplesmente bate no teto e você troca a compactação pelo erro "Prompt is too long". O auto-compact é um recurso que protege você, não um que atrapalha.

7. Três situações em que a rotina fixa sai pela culatra

Com essas especificações em mãos, fica claro onde "apertar de vez em quando, por via das dúvidas" custa dinheiro.

1. Apertar no meio da tarefa

Detalhes que você ainda ia usar são achatados no resumo. Ainda por cima, regras com paths: e CLAUDE.md aninhados caem fora, então o trabalho seguinte começa a furar as suas regras silenciosamente. É o tipo de degradação cuja causa é difícil de enxergar.

2. Apertar logo depois de uma pausa

O cache expirou, então todo o histórico é reprocessado antes de ser resumido. É o momento mais caro para o mesmo /compact — e a boa intenção de "deixa eu organizar antes de começar" vai direto para lá.

3. Apertar em uma sessão curta

Sem histórico que valha resumir, você só recebe Not enough messages to compact. Isso também acontece quando uma única colagem enorme encheu o contexto — e aí a resposta certa é /clear, não um resumo.

Invertendo, chega-se à regra: a compactação manual de maior valor é aquela feita imediatamente antes de você começar um trabalho longo. Apertar ali reduz a chance de o auto-compact interromper você no meio do caminho. O valor está no momento, não na quantidade.

8. Na prática — o que você faz antes importa mais

O que realmente muda o jogo com o /compact não é como você aperta, e sim o que você grava em arquivos antes de apertar. Como mostra a tabela da seção 3, o CLAUDE.md da raiz do projeto e a sua memória automática são reinjetados do disco. Tudo o que estiver escrito ali sobrevive a qualquer número de compactações.

Há mais uma propriedade que costuma passar batido. Editar o CLAUDE.md durante uma sessão não passa a valer na hora. A documentação coloca assim: "as edições não invalidam o cache, mas também não entram em vigor. O novo conteúdo é carregado no próximo /clear, /compact ou reinício." Lido ao contrário, isso significa que o /compact é também a operação que faz valer as regras decididas no meio da sessão.

Checklist para antes de apertar

  • Você escreveu as regras e decisões desta sessão em um arquivo? (Tudo o que só existe na conversa é diluído pelo resumo)
  • Você disse o que deve ser mantido? Dá para entregar um foco, como em /compact mantenha o plano de correção da autenticação e os resultados dos testes
  • O próximo trabalho é mesmo uma continuação? Se não tiver relação, o /clear é mais barato
  • O cache está quente agora? (Evite o momento logo após uma pausa longa)
  • Na dúvida, rode /context e meça o que está de fato ocupando espaço

E aqui está o ponto que quem cogita compactar manualmente mais deixa escapar. O hábito de "eu aperto por conta própria, de forma preventiva, porque tenho medo de ser compactado pelas minhas costas e perder o fio" é comum o bastante. Mas a documentação diz isto logo depois de explicar o auto-compact: para controlar o que é preservado através da compactação, adicione uma seção "Compact Instructions" ao seu CLAUDE.md ou rode /compact com um foco (How Claude Code works).

Em outras palavras, especificar um foco não é privilégio de quem aperta na mão. Coloque isso no CLAUDE.md e vale também para a compactação que roda enquanto você está longe da mesa. Se o objetivo da sua rotina manual preventiva é decidir como o contexto será podado, esta é a versão que de fato funciona — a rotina manual só ajuda enquanto você está olhando.

Escrever isso não é difícil. O exemplo da própria documentação é assim.

Instruções de compactação padrão colocadas no CLAUDE.md (exemplo da documentação oficial)

# Compact instructions

When you are using compact, please focus on test output and code changes

Já que estamos falando disso, eis como este site opera. O CLAUDE.md do repositório deste blog carrega duas regras há bastante tempo: "sugira o /compact ao usuário quando o contexto ficar longo" e "antes de rodar o /compact, salve na memória tudo o que deve virar regra — feedbacks, decisões de abordagem". Este artigo mesmo foi escrito em uma sessão que passou por uma compactação. No uso diário, não é a primeira regra que se paga, e sim a segunda. Colocar de antemão nos arquivos aquilo que vale guardar funciona muito melhor do que tentar moldar o resumo com esforço.

Mais uma coisa que vale acrescentar: o /compact não é o único jeito de reduzir contexto. A orientação oficial sobre custos recomenda delegar a subagents os trabalhos de saída pesada — rodar testes, buscar documentação, processar logs. Um subagent tem a própria janela de contexto e devolve apenas um resumo, então o contexto principal nem chega a inchar. Arranjar as coisas para não precisar de compactação vence compactar bem.

9. Duas mensagens que você pode encontrar

Duas mensagens que aparecem na prática são bem pouco autoexplicativas.

Mensagem O que significa O que fazer
Not enough messages to compact. Não há conversa que valha resumir. Também acontece quando uma única colagem enorme encheu o contexto Recomece com /clear
Autocompact is thrashing: the context refilled to the limit... A compactação deu certo, mas um arquivo ou uma saída de ferramenta gigante encheu o contexto de novo logo em seguida, várias vezes. Ele parou para evitar um laço infinito Os quatro passos ao lado (na ordem recomendada pela documentação)

A recuperação do segundo caso está descrita em ordem na documentação. (1) Leia arquivos enormes em pedaços, por faixa de linhas ou por função. (2) Compacte com uma instrução que nomeie a saída que você quer descartar (por exemplo /compact mantenha só o plano e o diff). (3) Mova esse trabalho para um subagent, para que rode em uma janela de contexto separada. (4) Se a conversa anterior já não for necessária, /clear. O revelador é que o passo 1 vem primeiro: a documentação está dizendo, na prática, que isto não é um problema de compactação, é um problema de leitura.

Resumo

Você não precisa rodar o /compact manualmente em intervalos fixos. O auto-compact roda de qualquer forma, e é o mesmo processamento. Apertá-lo você mesmo compra exatamente duas coisas — escolher o momento e especificar o que manter — e as duas se pagam em um único lugar: entre tarefas.

No custo, a rotina fixa também perde. O preço de uma compactação é definido pelo cache estar quente ou não, então o "deixa eu organizar antes de começar" depois da pausa é a versão mais cara dela. Se um recomeço do zero resolve, o /clear é gratuito; se você está mudando de direção, o /rewind é mais barato porque volta a um cache existente; e se você só quer ler um resumo, o /recap deixa o histórico em paz. Escolher o certo entre os quatro vence apertar o mesmo com mais frequência.

A conclusão mais prática, porém, está fora da questão de como apertar. Tudo o que você não pode perder pertence a um arquivo, não à conversa. O CLAUDE.md da raiz do projeto e a sua memória automática são reinjetados do disco, enquanto regras com paths: e CLAUDE.md aninhados caem fora em silêncio. Conhecer essa assimetria é o que separa uma sessão longa que se sustenta de uma que se degrada sem avisar.

FAQ

Q1. Afinal, de quantos em quantos minutos eu devo apertar o /compact?

Não se deve decidir isso pelo tempo. O único momento recomendado é logo depois de uma tarefa terminar e antes de começar a próxima tarefa longa. A documentação diz "em um ponto de corte natural do trabalho, por exemplo entre tarefas" e não indica nenhum limiar de tempo ou porcentagem.

Q2. Posso simplesmente deixar tudo por conta do auto-compact?

O automático e o manual são o mesmo processamento; só o momento difere. O detalhe é que o automático pode interromper você no meio de uma tarefa. Apertar uma vez na mão antes de um trecho longo de trabalho reduz a chance dessa interrupção. E você também pode dar instruções ao automático — escreva-as no CLAUDE.md sob um título # Compact instructions e elas valem para uma compactação que rode enquanto você está longe da mesa (veja a seção 8).

Q2-2. Depois de ele compactar sozinho, minhas instruções parecem não pegar mais

Não é impressão sua. A documentação afirma que "instruções detalhadas do início da conversa podem ser perdidas". Além disso, regras com paths: e CLAUDE.md aninhados caem fora até que o arquivo correspondente seja lido de novo, e as skills invocadas são descartadas da mais antiga para a mais nova assim que ultrapassam 25.000 tokens no total. Não é tanto que o conteúdo desapareça, e sim que as regras seguidas vão minguando em silêncio, de modo que o trabalho continua e só a precisão cai. Três contramedidas: (1) mova para o CLAUDE.md da raiz as regras que você quer permanentes, onde elas são reinjetadas; (2) nomeie o que manter com # Compact instructions; (3) use o /autocompact para disparar mais cedo, de modo que a compactação não aconteça bem no teto.

Q3. Devo usar o /compact ou o /clear?

/compact se o próximo trabalho continua o anterior, /clear se não continua. A documentação de custos afirma sem rodeios que "se você quer recomeçar do zero em vez de continuar, o /clear é gratuito". Passe um nome ao /clear e você pode voltar à sessão pela lista do /resume, então não há nada a temer em perder.

Q4. A compactação apaga as regras do meu CLAUDE.md?

O CLAUDE.md da raiz do projeto não é apagado — ele é reinjetado do disco. O que some são as regras com front matter paths: e os CLAUDE.md aninhados em subdiretórios, que não voltam até que um arquivo correspondente seja lido de novo. Para regras que você quer permanentes, remova a chave paths: ou mova-as para o CLAUDE.md da raiz.

Q5. Dá para desligar o auto-compact?

Dá (a configuração autoCompactEnabled em false, "Auto-compact" no /config ou a variável de ambiente DISABLE_AUTO_COMPACT). Não é recomendado. Desligar não reduz o seu contexto; você simplesmente bate no teto e recebe um erro. Se o que você quer é que ele rode mais cedo, a jogada correta não é desativá-lo, e sim estreitar a janela com o /autocompact.

Q6. Quantos tokens o /compact consome?

Varia enormemente conforme o cache esteja quente ou não. Aperte no meio da sessão e o prefixo é lido do cache, custando, nas palavras da documentação, muito menos do que o tamanho do contexto sugere. Aperte depois de uma pausa mais longa que a vida útil do cache e todo o histórico é reprocessado sem cache, tornando o mesmo comando o mais caro que ele pode ser. A vida útil do cache é de uma hora em assinatura e de cinco minutos por padrão via chave de API ou provedor de nuvem.

Q7. Posso especificar o que fica guardado?

Pode. Escreva uma instrução depois do /compact e o resumo é produzido com aquele foco (por exemplo /compact mantenha o plano de correção da autenticação e os resultados dos testes). Se a mesma instrução serve sempre, crie um título # Compact instructions no CLAUDE.md e ela passa a valer como padrão.

Q8. Por que as respostas parecem lentas logo depois de uma compactação?

O turno imediatamente posterior a uma compactação não é pesado. Segundo a documentação, esse turno reconstrói o cache a partir de um resumo curto, então não é a parte lenta. O que você está sentindo costuma ser a própria execução da compactação, enquanto o resumo é gerado, ou um caso em que você apertou com o cache já frio.

Q9. Existe um recurso chamado "microcompactação"?

O comportamento existe — a documentação explica que as saídas antigas de ferramentas são descartadas primeiro e que a conversa só é resumida se necessário, o que é uma afirmação explícita de que algo acontece antes da sumarização. Mas em 8 de agosto de 2026 a documentação oficial não usa o nome "microcompactação". O termo vem de textos de terceiros, não da Anthropic, então trate-o como tal.

Artigos relacionados