Claude Code: quando usar /clear, /compact ou nova sessão

Claude Code: quando usar /clear, /compact ou nova sessão

Use /clear quando a tarefa mudou e nada da conversa anterior ajuda mais. Use /compact quando a tarefa continua, mas o histórico ficou longo e você quer manter o fio. Abra uma nova sessão quando quiser separar trabalhos ou retomar outro dia. Em todos os casos, o que precisa valer sempre deve estar no CLAUDE.md, não na conversa.

Principais pontos

• /clear apaga o histórico da conversa atual e começa do zero, mantendo os arquivos do projeto e o CLAUDE.md.
• /compact troca o histórico por um resumo, então economiza espaço, mas detalhes finos podem se perder no resumo.
• Nova sessão é a melhor escolha para trabalhos independentes ou quando a conversa já está confusa.
• Regras de estilo, comandos de teste e restrições do projeto pertencem ao CLAUDE.md, porque são lidas de novo a cada sessão.
• Antes de limpar ou compactar, registre decisões e pendências em um arquivo do repositório, para que elas não dependam da memória da conversa.

Por que o contexto enche e o que isso muda na prática

O contexto do Claude Code é tudo o que o modelo enxerga em uma conversa: suas mensagens, as respostas, arquivos lidos, saídas de comandos e resultados de ferramentas. Esse espaço é limitado. Se você quiser entender o conceito de base, o artigo sobre janela de contexto em IA explica o que é e como não estourar, e o texto sobre tokens em IA mostra por que esse volume também pesa no custo.

O ponto prático é que o contexto não enche só com conversa. Uma leitura de arquivo grande, uma saída longa de teste ou uma busca que retorna muitos resultados ocupam muito espaço. Conforme o espaço se aproxima do limite, dois problemas aparecem: o Claude Code pode compactar a conversa automaticamente, e a qualidade pode cair, porque instruções antigas ficam diluídas entre muito material irrelevante.

A literatura técnica sobre agentes trata isso como engenharia de contexto: o objetivo é manter na janela o menor conjunto de informações que ainda permita fazer bem a tarefa. A Anthropic descreve essa ideia em Effective context engineering for AI agents. Os comandos /clear e /compact são as duas ferramentas manuais mais diretas para isso.

Uma observação sobre o que é documentação e o que é prática: o que cada comando faz está na documentação oficial do Claude Code e pode mudar entre versões, então confirme na versão que você usa. As recomendações de quando usar cada um, neste texto, são prática de implementação e hipóteses de trabalho, não garantias.

O que /clear e /compact fazem, e o que se perde em cada um

O /clear começa uma conversa em branco dentro da mesma pasta de projeto. Perde-se todo o histórico: o que você pediu, o que o modelo respondeu, as decisões tomadas no caminho e os arquivos que ele havia lido. Não se perde o código em disco, as alterações já gravadas nem o CLAUDE.md, que é carregado de novo.

O /compact faz outra coisa: em vez de apagar, ele pede um resumo da conversa e passa a trabalhar com esse resumo no lugar do histórico completo. Você pode acrescentar instruções depois do comando, indicando o que deve ser preservado, por exemplo as decisões de arquitetura e a lista de arquivos alterados. O que se perde é o detalhe: trechos literais de saídas, o raciocínio intermediário, tentativas descartadas e nuances que o resumo não capturou.

A diferença, em uma frase: /clear descarta tudo e confia nos arquivos; /compact descarta o excesso e confia no resumo. Os dois exigem que o estado importante esteja fora da conversa, ou seja, no código, em notas e no CLAUDE.md.

Se você não compactar, o Claude Code pode fazer isso sozinho perto do limite. Isso é conveniente, mas tem um risco: o resumo automático acontece no momento em que você não escolheu o foco. Por isso, compactar manualmente em um ponto estável da tarefa, com instruções do que manter, costuma dar resultado mais previsível.

Quando abrir uma nova sessão em vez de limpar

Limpar a conversa e abrir uma nova sessão parecem iguais, mas servem a situações diferentes. A nova sessão é útil quando você quer manter a anterior disponível para consulta ou retomada, enquanto o /clear é mais simples quando você só quer recomeçar no mesmo terminal e não precisa voltar.

O Claude Code permite retomar conversas anteriores (com opções de continuar a última ou escolher uma da lista, conforme a documentação da sua versão). Isso torna a nova sessão uma forma barata de separar trabalhos sem perder o histórico.

Prefira uma nova sessão nestes casos:

• A tarefa é independente da anterior, como passar de uma correção de bug para uma documentação.
• A conversa acumulou desvios, tentativas falhas e correções, e o modelo começou a repetir erros já resolvidos.
• Você vai trabalhar em outro dia ou outra pessoa vai assumir.
• Você quer testar uma abordagem alternativa sem contaminar a principal.

A ideia de retomar o trabalho com estado explícito, e não com memória da conversa, aparece também em Effective harnesses for long-running agents. A lição geral é a mesma: quem passa o bastão entre sessões deve deixar um registro claro do que foi feito e do que falta.

Guia de decisão: limpar, compactar ou recomeçar

Use esta sequência como regra de bolso. Ela é uma hipótese de trabalho que cada equipe deve ajustar com a própria experiência.

• A próxima tarefa não tem relação com a anterior? Use /clear.
• A tarefa é a mesma, a conversa está longa, mas o rumo está certo? Use /compact, com instruções do que preservar.
• A conversa está confusa, com muitas tentativas descartadas? Registre o estado em um arquivo e abra uma nova sessão.
• O modelo esqueceu uma regra importante do projeto? Não repita a regra na conversa: coloque no CLAUDE.md.
• Você vai parar e voltar depois? Escreva o ponto de parada em um arquivo de notas e encerre a sessão.

E um passo a passo curto para quando você decidir compactar ou limpar:

• Peça ao Claude Code um resumo do estado atual: o que foi feito, o que falta e quais decisões foram tomadas.
• Salve esse resumo em um arquivo do repositório, como um arquivo de notas da tarefa, e revise o texto.
• Confira se o que está pendente de commit foi gravado ou anotado.
• Execute /compact com instruções de foco, ou /clear se a tarefa mudou.
• Na conversa nova, peça para ler o arquivo de notas e confirmar o próximo passo antes de agir.

Como manter as instruções essenciais no CLAUDE.md

O CLAUDE.md é o arquivo de instruções persistentes do projeto. Segundo a documentação, ele é lido no início de cada sessão, o que significa que sobrevive ao /clear e a novas sessões. Em geral ele também continua valendo depois de uma compactação, mas vale testar isso na sua versão: depois de compactar, pergunte ao modelo quais regras do projeto ele está seguindo.

O que colocar nele:

• Comandos para rodar testes, formatar o código e subir o ambiente local.
• Convenções do projeto: estrutura de pastas, padrão de nomes, bibliotecas preferidas.
• Restrições: o que nunca deve ser alterado, quais arquivos são gerados e quais ambientes não podem ser tocados.
• Regras de segurança e dados: não colar credenciais, não ler arquivos com dados pessoais de clientes, mascarar logs antes de analisar.
• Definição de pronto: o que precisa passar antes de considerar uma tarefa concluída.

O que deixar de fora: histórico de tarefas, decisões que valem só para esta semana e textos longos de documentação que o modelo pode ler sob demanda. Um CLAUDE.md inchado vira ruído e consome contexto em toda sessão. Mantenha curto, específico e verificável. Uma regra como use o formato X para datas é melhor que escreva código de qualidade.

Para procedimentos mais longos e repetíveis, o mais indicado é separar do CLAUDE.md. O artigo sobre skills no Claude Code mostra como empacotar rotinas da equipe, e o texto sobre configurar MCP no Claude Code explica os escopos local, projeto e usuário para conectar ferramentas externas sem encher a conversa de instruções.

Um hábito simples ajuda: sempre que você se pegar repetindo a mesma instrução em sessões diferentes, é sinal de que ela deve ir para o CLAUDE.md. E sempre que uma regra do arquivo deixar de ser verdadeira, remova. Instrução desatualizada é pior que instrução ausente.

Cenário ilustrativo e como aplicamos o método

Cenário ilustrativo: uma equipe pequena mantém o sistema de pedidos de uma loja. Na manhã, uma pessoa pede ao Claude Code para corrigir o cálculo de frete. A conversa fica longa, com várias leituras de arquivos e saídas de teste. Antes do almoço, o frete está resolvido e ela precisa ajustar uma tela sem relação com isso.

A escolha é /clear, porque o frete terminou e a tela é outro assunto. Antes de limpar, ela pede um resumo do que mudou e salva em um arquivo de notas. À tarde, ao implementar a tela, a conversa cresce de novo, mas a tarefa segue no rumo certo, então ela usa /compact pedindo para preservar a lista de componentes alterados e a decisão sobre o formato dos campos. No dia seguinte, outra pessoa abre uma nova sessão, lê o arquivo de notas e continua. As regras de teste e de estilo nunca precisaram ser repetidas, porque estão no CLAUDE.md.

Aplicando o método que usamos em projetos de IA, o raciocínio é parecido com o de qualquer operação com agentes:

• Mapear: observar como a equipe usa o Claude Code hoje, onde as sessões se perdem e quais instruções são repetidas.
• Limitar: definir o que o CLAUDE.md pode conter, o que não pode (dados pessoais, credenciais) e quais pastas ou comandos exigem aprovação.
• Pilotar: testar a rotina de limpar, compactar e registrar notas em um projeto real, com um critério combinado, como menos retrabalho por instrução repetida.
• Transferir: documentar a rotina, entregar o CLAUDE.md revisado e decidir se expande, ajusta ou para.

Se o uso for por pessoas que não programam, o texto sobre Claude Code para não programadores traz o contexto de automações no terminal com os mesmos cuidados.

Perguntas frequentes

O /clear apaga o meu código ou o CLAUDE.md? Não. O /clear apaga apenas o histórico da conversa atual. Os arquivos no disco, incluindo o código já gravado e o CLAUDE.md, continuam como estavam, e o CLAUDE.md é lido de novo no início da nova conversa.

É melhor compactar manualmente ou esperar a compactação automática? Em geral, compactar manualmente em um ponto estável dá mais controle, porque você pode indicar o que preservar. A compactação automática funciona como proteção quando o limite se aproxima, mas o resumo acontece sem o seu foco. Como o comportamento pode mudar entre versões, vale conferir a documentação oficial.

O que fazer quando o modelo esquece uma regra do projeto depois de compactar? Primeiro, verifique se a regra está no CLAUDE.md e se está escrita de forma curta e verificável. Se estiver só na conversa, ela pode ter sido perdida no resumo. Mova a regra para o arquivo e, se necessário, abra uma nova sessão para garantir que ela seja carregada.

Posso colocar dados de clientes no CLAUDE.md ou nas notas de tarefa? Não é recomendado. Arquivos de instruções e notas ficam no repositório e podem ser compartilhados, então devem conter regras e decisões, não dados pessoais ou credenciais. Se o trabalho envolve dados de clientes, avalie as obrigações da LGPD, inclusive sobre transferência internacional, no artigo sobre transferência internacional de dados com IA.

Fontes

• Anthropic: Effective context engineering for AI agents
• Anthropic: Effective harnesses for long-running agents