Claude Code: como evitar sessões lentas e caras

Como evitar que uma sessão longa do Claude Code fique lenta e cara

Uma sessão longa do Claude Code fica lenta e cara porque cada turno reenvia todo o contexto, que continua a crescer. A correção é aplicar uma rotina de manutenção numa ordem fixa. Execute /context para ver o que está a ocupar a janela de contexto, remova os itens pelos quais paga em cada pedido e, em seguida, use /clear entre tarefas não relacionadas e /compact com uma instrução dentro de uma única tarefa longa. Trabalhe em períodos contínuos, porque uma cache de prompts fria transforma uma leitura barata numa reescrita completa de tudo o que disse.

A explicação para o contador continuar a avançar está em o contador de tokens por trás de uma sessão de agente.

Leia /context antes de alterar qualquer coisa

Não adivinhe o que preenche a janela. O Claude Code informará isso.

/context [all] mostra o uso atual do contexto numa grelha colorida, com sugestões de otimização para ferramentas que usam muito contexto e para excesso de memória; all expande a discriminação por item no modo de ecrã inteiro. Leia o resultado como cinco categorias.

• O prompt do sistema. As instruções do próprio mecanismo do Claude Code. Fixas durante a sessão.
• Definições das ferramentas. O esquema de todas as ferramentas que o agente pode chamar, incluindo todos os servidores MCP (Model Context Protocol) ligados.
• Ficheiros de memória. CLAUDE.md e a memória automática, carregados no início da sessão.
• Ficheiros e resultados das ferramentas. Todos os ficheiros lidos e tudo o que os seus comandos devolveram.
• Histórico de mensagens. As suas mensagens e as respostas do agente.

Os primeiros três representam um custo fixo, pago em todos os pedidos durante toda a sessão. Os dois últimos crescem. Reduza o custo fixo uma vez, no início; faça a gestão da parte crescente continuamente.

Duas cadeias indicam que a janela está cheia:

Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.

A primeira é um limite rígido, e o pedido é recusado; o erro correspondente da API (application programming interface) é Prompt is too long. A segunda é uma janela de compactação, que pode ficar abaixo da janela de contexto real num modelo de 1 milhão de tokens. Os pedidos continuam a ser aceites depois desse ponto, pelo que se trata de um aviso, não de uma recusa.

Num plano pago, /usage acrescenta a outra metade, assinalando comportamentos como contexto longo ou falhas de cache e atribuindo o uso recente a competências, subagentes e servidores MCP individuais. Se indicar que o limite disponível já foi consumido, qual janela de limite está a aguardar determina se reduzir o contexto o ajuda agora ou se precisa de outro caminho para retomar o trabalho.

CLAUDE.md é um custo permanente, portanto mantenha-o enxuto

O seu CLAUDE.md é carregado no início da sessão e permanece nesse contexto. Se contiver um procedimento de implantação detalhado, esses tokens ficam presentes enquanto corrige um erro de digitação num ficheiro de teste. A orientação da Anthropic é incluir apenas o essencial e manter o ficheiro abaixo de 200 linhas.

Mova os procedimentos para skills. Uma skill é carregada apenas quando é invocada, portanto um workflow executado duas vezes por semana não tem custo nos outros dias. As skills têm o seu próprio orçamento depois de uma compactação: os corpos são reinjetados, com um limite de 5,000 tokens por skill e 25,000 no total, e as mais antigas são descartadas primeiro. A truncagem mantém o início do ficheiro, portanto coloque as instruções mais importantes perto do topo de SKILL.md.

O que sobrevive a uma compactação determina onde uma instrução deve ficar.

• O system prompt e o estilo de saída permanecem inalterados, porque não fazem parte do histórico de mensagens.
• O CLAUDE.md na raiz do projeto, as regras sem escopo e a memória automática são reinjetados a partir do disco.
• Uma regra com frontmatter paths: é perdida até que um ficheiro correspondente seja lido novamente.
• Um CLAUDE.md aninhado num subdiretório é perdido até que um ficheiro desse subdiretório seja lido novamente.
• Os hooks não são afetados, porque um hook é executado como código e nunca entra no contexto.

Por isso, uma regra da qual depende deve ficar no CLAUDE.md na raiz do projeto: o Claude Code limpa primeiro as saídas antigas das ferramentas e depois faz um resumo, portanto as instruções do início da conversa podem ser perdidas. Edite a memória com /memory. O Claude Code mantém a cópia carregada no início da sessão, portanto uma redução no meio da sessão mantém a cache do prompt e só é aplicada no próximo /clear, /compact ou reinício. A perda de contexto é apenas uma das razões para uma regra deixar de ser seguida. Quando a regra ainda está claramente na janela e mesmo assim é ignorada, analise as outras causas antes de a reescrever.

limpe entre tarefas, compacte dentro de uma só

Estas duas opções parecem intercambiáveis, mas têm custos muito diferentes.

/clear [name] inicia uma nova conversa com o contexto vazio. Não envia nenhum pedido, portanto não tem custo. Passe um nome para identificar a conversa anterior no seletor /resume; /reset e /new são aliases. Use-o assim que mudar para uma tarefa não relacionada, porque, caso contrário, a tarefa anterior seria reenviada e cobrada novamente em cada mensagem da nova tarefa.

/compact [instructions] liberta espaço no contexto e mantém a mesma conversa: resume o histórico até ao momento e substitui-o pelo resumo. Use-o dentro de uma tarefa longa, quando ainda precisa de continuidade.

Dê sempre uma instrução a /compact. Um /compact isolado resume com base num prompt predefinido que não sabe de que parte do trabalho ainda precisa. Um comando com instrução preserva essa informação:

/compact focus on the auth bug fix
/compact keep only the plan and the diff

Se compacta pelo mesmo motivo todas as vezes, adicione uma instrução permanente ao CLAUDE.md do projeto, sob um cabeçalho # Compact instructions. Numa nova sessão, /compact mostra Not enough messages to compact., o que significa apenas que ainda não existe histórico.

Aqui confundem-se dois custos. O pedido de resumo partilha o seu prefixo, portanto lê a cache existente em vez de processar novamente o histórico, e a maior parte do tempo é usada para gerar o resumo. Compactar um contexto grande continua a ser um pedido grande, porque a conversa resumida é a entrada. A interação depois da compactação não é a parte lenta: ela reconstrói a cache para um prompt muito mais curto.

Existem dois comandos mais económicos. /rewind [description] reverte o código e a conversa para um checkpoint; para um caminho que quer abandonar completamente, é melhor do que compactar, porque trunca a conversa para um prefixo que já está em cache. /recap adiciona um resumo como saída do comando em vez de substituir o histórico, mantendo intacto o prefixo em cache.

Quando a compactação automática é executada repetidamente, aparece o seguinte:

Autocompact is thrashing: the context refilled to the limit...

A compactação foi concluída, mas um ficheiro ou a saída de uma ferramenta voltou a preencher a janela várias vezes seguidas, por isso o Claude Code deixou de tentar novamente. Para recuperar, leia o ficheiro demasiado grande por intervalos de linhas, execute /compact com um foco que elimine a saída extensa, transfira esse trabalho para um subagente ou use /clear se a conversa anterior já tiver terminado.

Os servidores MCP são um custo fixo

Cada servidor MCP ao qual se liga é acrescentado a todos os pedidos durante toda a sessão. O custo aplica-se mesmo que não o utilize.

O Claude Code reduz este impacto. Por predefinição, as definições das ferramentas MCP são adiadas. Assim, apenas os nomes das ferramentas entram no contexto até o Claude utilizar uma ferramenta específica. Execute /context para ver o custo real dos seus servidores e /mcp disable <name> para remover um que não vai utilizar hoje. Se executar os seus próprios servidores MCP num VPS, o mesmo cálculo limita o número de ferramentas que cada servidor deve expor.

Faça isto no início de uma sessão. Enquanto as definições permanecerem adiadas, ligar ou desligar um servidor apenas acrescenta conteúdo à conversa, e a cache é preservada. Quando as definições são carregadas no prefixo, porque a pesquisa de ferramentas está desativada ou porque um servidor está excluído do adiamento, a mesma alteração faz com que o pedido seguinte volte a ler tudo.

Filtrar a saída detalhada das ferramentas antes de entrar no contexto

O resultado de uma ferramenta é uma entrada, e é reenviado em todas as mensagens seguintes. Uma execução de teste que despeja 20,000 tokens de saída não tem um custo único: paga por ela novamente em todas as mensagens até que saia da janela.

Filtre na origem. Um hook que reduz uma execução de teste apenas às falhas antes de Claude a ver transforma essa saída extensa em algumas centenas de tokens, nesta mensagem e em todas as retransmissões seguintes:

npm test 2>&1 | grep -E "FAIL|Error:" | head -40

Os hooks nunca entram no contexto por si próprios, porque são executados como código. Faça isto para qualquer ferramenta cuja saída ultrapasse uma janela do terminal. A mesma lógica aplica-se a um ficheiro com 3,000 linhas: peça o intervalo de linhas de que precisa, porque o ficheiro completo permanece na janela assim que chega.

Defina o âmbito do que o agente lê e delegue o trabalho ruidoso

Um prompt que identifica o ficheiro e o sintoma lê esse ficheiro. Um pedido aberto para organizar o projeto lê tudo o que o agente considerar relevante, e cada uma dessas leituras permanece na janela de contexto.

Delegue o trabalho verboso a um subagente. As execuções de testes e o processamento de logs consomem contexto real; um subagente mantém essa saída na sua própria janela e devolve apenas um resumo. A contrapartida é que um subagente cria a sua própria cache, sem ocorrências na primeira chamada, e usa o período de validade de cinco minutos mesmo numa subscrição. A delegação protege de forma fiável o seu contexto principal. Nem sempre reduz o total de tokens.

O relógio da cache: trabalhe em períodos contínuos

O caching de prompts é o que torna o reenvio acessível: 0.1x da tarifa base de entrada para ler o prefixo, contra 1.25x para o escrever, ou 2x para o escrever com a validade de uma hora. Cada utilização atualiza a entrada sem custo adicional, por isso o relógio começa novamente na última utilização. Estes multiplicadores mostram a estrutura do custo, mas não o seu valor, por isso associe-os a quanto custa realmente um milhão de tokens para converter uma janela de contexto completa num valor em dólares.

A validade que obtém depende da forma como autentica, que é precisamente onde falha a afirmação genérica de que "a sua cache expira ao fim de cinco minutos".

• Numa subscrição Claude, o Claude Code solicita automaticamente a validade de uma hora.
• Depois de ultrapassar o limite do seu plano e começar a utilizar créditos de utilização, essa utilização é faturada, pelo que a validade volta a ser de cinco minutos.
• Com uma chave de API ou um fornecedor de cloud, mantém-se em cinco minutos. ENABLE_PROMPT_CACHING_1H=1 ativa a validade de uma hora, e FORCE_PROMPT_CACHING_5M=1 força o regresso a cinco minutos.

O conselho sobre o ritmo é o mesmo em qualquer caso: trabalhe em períodos contínuos, porque uma pausa superior à validade faz com que o seu próximo turno volte a escrever todo o prefixo acumulado. Uma sessão do Claude Code desligada num tmux não tem custos enquanto está inativa, e é a cache quente que permite esse tempo de inatividade.

Algumas ações eliminam a cache enquanto ainda está a trabalhar: mudar de modelo, alterar o nível de esforço, ativar o modo rápido, ligar ou desligar um servidor MCP, ativar ou desativar um plugin, recusar uma ferramenta completa, compactar e atualizar o Claude Code. /model é a surpresa habitual, porque cada modelo tem a sua própria cache. Por isso, o pedido seguinte lê todo o histórico sem acertos na cache, mesmo que o conteúdo seja idêntico. Essa releitura é faturada às tarifas do modelo de destino, pelo que mudar para Fable a meio da sessão cobra todo o histórico acumulado à tarifa de entrada publicada do Fable 5.

Editar ficheiros, editar CLAUDE.md, invocar skills e comandos, executar /recap, retroceder e iniciar um subagente mantêm a cache. A cache está associada a uma máquina e a um diretório, por isso duas sessões em diretórios diferentes não utilizam a cache uma da outra. Esta associação segue a CLI e não a sua conta, pelo que nada disso é transferido para a aplicação de desktop Claude, que no Linux é uma instalação beta separada, ao lado da CLI.

Para verificar se o caching está a funcionar, leia current_usage. cache_creation_input_tokens foi escrito à tarifa de escrita da cache; cache_read_input_tokens foi servido a aproximadamente um décimo da tarifa de entrada normal. Uma proporção elevada entre leituras e criações é saudável. Se a criação continuar elevada em todos os turnos, algo no seu prefixo está a mudar continuamente.

Uma janela de contexto maior resolve este problema?

Em parte. Vários modelos atuais suportam uma janela de contexto de 1 million token, e a compactação funciona da mesma forma com esse limite maior. A economia não muda, porque o prompt completo continua a ser reenviado e continua a ser faturado em cada turno. Uma janela maior determina quando é obrigado a agir; a higiene determina o custo. Se o problema for a fatura, e não o limite, qual plano Claude se adequa à forma como trabalha determina se está a gastar dólares ou o saldo do plano.

A edição e a compactação do contexto na API são coisas diferentes

Se está a criar o seu próprio agente na Messages API, não existem comandos de barra e terá de implementar este comportamento. Reserve trabalho para isso desde o início, porque a API não tem um nível gratuito além de um pequeno crédito de registo, e cada turno do histórico não reduzido é faturado na totalidade. O fornecedor escolhido determina esse cálculo antes de qualquer redução, por isso, se a escolha ainda estiver em aberto, calcule o custo da mesma carga de trabalho nas duas APIs em vez de comparar as tarifas anunciadas por token. Há duas funcionalidades do lado do servidor que fazem este trabalho, e não são a mesma funcionalidade.

Edição do contexto limpa seletivamente conteúdo específico do histórico da conversa à medida que este cresce, substituindo cada resultado limpo por texto de marcador para que Claude saiba que algo foi removido. É uma funcionalidade beta: envie anthropic-beta: context-management-2025-06-27 e configure as estratégias em context_management.edits. clear_tool_uses_20250919 limpa os resultados das ferramentas e clear_thinking_20251015 gere blocos de raciocínio. O valor predefinido de trigger é 100,000 tokens de entrada, o de keep é as últimas 3 utilizações de ferramentas e o de clear_tool_inputs é false, por isso as entradas permanecem e apenas os resultados são removidos.

A compactação gera um resumo e substitui por ele todo o histórico da conversa. Também é uma funcionalidade beta: envie anthropic-beta: compact-2026-01-12 e use o tipo de edição compact_20260112. O acionador predefinido é {"type": "input_tokens", "value": 150000}, e o valor tem de ser pelo menos 50,000.

A compactação tem uma regra de transição que pode causar falhas silenciosas nos agentes. A resposta começa com um bloco de conteúdo compaction que contém o resumo, seguido pelo bloco de texto normal. Tem de passar esse bloco de volta nos pedidos seguintes, e a API elimina então todos os blocos de conteúdo anteriores. Na prática: anexe response.content na totalidade, não apenas o texto.

A documentação da Anthropic chama à compactação do lado do servidor a estratégia principal para gerir o contexto em conversas de longa duração, e à edição do contexto a opção para controlar com maior precisão o que é limpo. Verifique primeiro o suporte dos modelos. Os modelos Opus, Sonnet e Fable atuais suportam compactação; claude-haiku-4-5 não suporta, e a página de compactação contém a lista atualizada. Nenhuma das duas funcionalidades beta controla o próprio /compact do Claude Code, que a respetiva documentação descreve como um pedido único de resumo enviado pelo cliente.

FAQ

Por que a minha sessão do Claude Code fica mais lenta e mais cara quanto mais tempo fica aberta?

Porque a conversa inteira é enviada novamente a cada turno. Assim, uma pergunta de uma linha numa sessão aberta durante todo o dia inclui todo o conteúdo desse dia. O cache de prompts mantém esse custo baixo enquanto o cache está disponível, a 0.1x da taxa de entrada base para uma leitura. Quando um turno não encontra correspondência no cache, o mesmo prefixo é gravado novamente a 1.25x. Execute /context para ver o que está a ocupar a janela e leia como uma sessão do Claude Code é faturada para perceber o mecanismo.

Qual é a diferença entre /clear e /compact no Claude Code?

/clear inicia uma nova conversa com o contexto vazio. Não envia nenhum pedido, por isso não tem custo, e é a opção correta entre tarefas sem relação. /compact mantém a mesma conversa e substitui o histórico por um resumo, por isso é a opção correta dentro de uma tarefa longa. Indique um foco, como em /compact keep only the plan and the diff, porque essa instrução determina o que é preservado.

Como vejo o que está a ocupar a janela de contexto do Claude Code?

Execute /context ou /context all para obter a discriminação completa por item. O comando mostra o prompt do sistema, as definições das ferramentas, os servidores MCP, os ficheiros de memória e o histórico numa grelha colorida, com sugestões para ferramentas que consomem muito contexto e para o excesso de memória. Num plano pago, /usage também atribui o uso recente a skills, subagentes e servidores MCP individuais.

Devo usar uma janela de contexto de 1 million de tokens em vez de fazer compactação?

Uma janela maior adia o problema, mas não o resolve. Vários modelos atuais usam uma janela de contexto de 1 million de tokens, incluindo Opus 4.8 e Sonnet 5, e a compactação funciona da mesma forma nesses modelos. Cada turno continua a reenviar o prompt completo e continua a ser faturado, por isso uma conversa com 400,000 tokens é cara quer caiba quer não.

Qual é a diferença entre a edição de contexto e a compactação na Claude API?

A edição de contexto limpa seletivamente conteúdo antigo, sobretudo resultados de ferramentas, deixando texto de marcador no lugar de cada resultado para que Claude saiba que foi removido. A compactação gera um resumo e substitui o histórico completo por esse resumo. A documentação da Anthropic chama à compactação a estratégia principal para conversas de longa duração e apresenta a edição de contexto como a opção granular. Ambas são funcionalidades beta com os seus próprios cabeçalhos e ambas são independentes de /compact do Claude Code.