Voltar para artigos

Medi 203 chamadas do Claude Code para entender por que o limite acaba

Abri o Claude Code de manhã, pedi duas features, ajustei um teste e na terceira tarefa veio o aviso de limite atingido. Eu tinha acabado de começar o dia.

Isso me aconteceu várias vezes até eu parar para medir. O limite segue uma regra simples, e quase sempre o que pesa é o que a sessão carrega a cada passo, não o que eu pedi.

Como o limite funciona

Os detalhes mudam com o plano e com o tempo, então confira a página de ajuda da Anthropic. O desenho geral:

  • Janela rolante de 5 horas. Começa na sua primeira mensagem e expira 5 horas depois. Não há reset fixo à meia-noite.
  • Teto semanal. Uma camada a mais para quem usa pesado todo dia.
  • Cota compartilhada. O uso no claude.ai e no Claude Code sai do mesmo balde.

Não vou citar quantas mensagens cabem em cada janela. Esse número muda a cada poucos meses e o artigo envelheceria junto com ele.

O modelo não lembra de nada, você reenvia tudo

Um LLM é stateless. Quando o Claude Code "lembra" do que você pediu há vinte minutos, ele está reenviando o histórico inteiro, junto com o system prompt, as definições de tools, o CLAUDE.md e a saída de cada comando que rodou.

Num chat normal, isso dá uma pergunta e uma resposta. No Claude Code dá um loop: ler arquivo, grep, editar, rodar teste, ler o erro, editar de novo. Cada passo é uma requisição que carrega o histórico acumulado.

Fui medir em vez de estimar. O Claude Code grava cada sessão em ~/.claude/projects/ e cada resposta traz o campo usage, com os tokens de entrada da chamada (novos, lidos do cache e escritos no cache). Somei isso numa sessão minha de um projeto real, sem nenhum /compact no meio:

sessão: 203 chamadas ao modelo, uma tarefa só

chamada   1:  41 mil tokens de contexto
chamada  21: 142 mil
chamada  61: 211 mil
chamada 101: 299 mil
chamada 141: 389 mil
chamada 201: 525 mil

mediana: 300 mil tokens por chamada
total de entrada processado: 62,4 milhões de tokens

O contexto cresceu mais de 12 vezes e cada chamada reenviou tudo o que veio antes. A sessão processou 62 milhões de tokens de entrada, e 200 das 203 chamadas rodaram com mais de 100 mil de contexto. Outras sessões longas que medi deram o mesmo formato: 266 chamadas e 68 milhões de tokens, 491 chamadas e 160 milhões.

Duas ressalvas sobre esses números. Eles medem tokens processados, não cota consumida: a Anthropic não publica o peso de cada tipo de token na cota, então não converto um no outro. E mais de 99% do volume foi leitura de cache, a parte mais barata. Mesmo assim, o custo cresce com o quadrado do número de passos, e não de forma linear. Parece o N+1 do ORM: cada operação sai barata, e a conta aparece na multiplicação.

Outro número que me surpreendeu: a primeira chamada de toda sessão já começa entre 32 e 44 mil tokens, antes de eu digitar qualquer coisa. Isso é system prompt, tools, CLAUDE.md e skills do meu setup. Quem usa muitos servidores MCP ou instruções longas começa ainda mais alto.

O cache expira

O Claude Code usa prompt caching. O prefixo que não mudou entre uma chamada e outra é lido de um cache, bem mais barato que processar tudo de novo. Por isso sessões contínuas rendem mais do que a conta bruta sugere.

O cache expira por inatividade. Se você sai para almoçar e volta escrevendo "continua", a primeira requisição reprocessa o contexto inteiro a preço cheio. Com a sessão em 150 mil tokens, esse "continua" sai caro. É o cache miss depois de um deploy, só que no seu terminal.

De onde vem o vazamento

Quando o limite acaba rápido, eu procuro nesta ordem:

  1. Sessão que virou o dia inteiro. Sem /clear, a feature nova carrega o debug da manhã. Cada passo do bug de hoje reenvia o de ontem.
  2. CLAUDE.md e skills grandes. Entram em toda chamada. Um arquivo de 800 linhas é cobrado a cada passo do loop.
  3. Servidores MCP com dezenas de tools. Os schemas ocupam contexto antes de você digitar. Rode /context numa sessão recém-aberta e veja quanto já está ocupado.
  4. Output verboso de comando. npm install, log de teste com 3 mil linhas, git log sem limite. Tudo vira histórico, e histórico é reenviado.
  5. Modelo forte em tarefa mecânica. Renomear variável e achar onde uma função é chamada com o modelo mais caro é usar guindaste para abrir cerveja.
  6. Exploração sem foco. "Dá uma olhada no projeto inteiro" faz o agente ler dezenas de arquivos, e cada arquivo entra inteiro no contexto.

/compact resume, mas quem decide o resumo é o modelo

O /compact resume a conversa e libera espaço, e o auto-compact dispara sozinho quando a janela enche. Eu uso os dois.

O limite é que o modelo escolhe o que sobrevive. A decisão de arquitetura de uma hora atrás pode virar uma frase vaga ou sumir, e você só percebe quando o agente refaz o que já tinha descartado.

Dá para guiar com instruções (/compact foque nas decisões de schema e nos testes que falharam) e isso melhora bastante. Ainda é um resumo gerado no meio do trabalho, que você não revisou.

Handoff: o resumo escrito por você, em arquivo

O que mudou meu consumo foi tratar a sessão como descartável. O estado da tarefa fica em um arquivo, e o contexto serve só para trabalhar.

É a passagem de turno de plantão: quem sai escreve o que está acontecendo, quem entra lê e continua, sem herdar a memória inteira do turno anterior.

O fluxo:

  1. Uma tarefa por sessão.
  2. Perto de 100 mil tokens, ou na mudança de fase, peço o handoff.
  3. O agente escreve um arquivo (.handoff/<tarefa>.md).
  4. /clear.
  5. Na sessão nova, o agente lê só esse arquivo e continua.

Automatizei com dois comandos customizados, /handoff para escrever e /pickup para retomar. O comando pouco importa, o que vale é o formato. Um handoff cabe em uma página (o exemplo abaixo é ilustrativo, não é de um projeto real):

# Handoff: migração do checkout para idempotency keys

## Objetivo
Evitar cobrança duplicada em retry do gateway.

## Estado atual
- Tabela `idempotency_keys` criada e migrada (migration 0042).
- Middleware aplicado em POST /checkout. Falta o /refund.

## Decisões (e por quê)
- Chave por (tenant_id, request_id), não só request_id: dois tenants
  mandavam o mesmo UUID de teste.
- TTL de 24h. Menos que isso quebra retry de webhook tardio.

## Falta fazer
1. Aplicar o middleware em /refund.
2. Teste de concorrência com 50 requests simultâneos na mesma chave.

## Armadilhas
- `go test ./...` leva 4 minutos. Rodar só `./internal/checkout/...`.
- Não mexer em `legacy/payments`, está congelado.

## Arquivos tocados
internal/checkout/handler.go, internal/checkout/idempotency.go,
migrations/0042_idempotency_keys.sql

Ficam as decisões com o motivo, o que falta e o que não fazer. Ficam de fora o diff, o log do último teste e a conversa. O agente recupera isso lendo o código quando precisar.

Uma sessão nova com esse arquivo começa no piso do setup (uns 40 mil tokens no meu caso) mais a página do handoff. A sessão velha estava em 525 mil e cada passo reenviaria tudo isso.

Onde o handoff falha

  • Handoff longo anula o ganho. Passou de uma página, você está duplicando o contexto que queria descartar. Corte.
  • Em tarefa pequena, é exagero. Para corrigir um typo, basta o /clear. Handoff serve para trabalho que atravessa sessões.
  • Depende de disciplina. Dar /clear sem escrever o handoff perde o estado. Por isso virou comando e deixou de ser lembrete mental.

O resto do protocolo

  • /context. Mostra system prompt, tools, memória e conversa separados. Olhe antes de culpar o limite.
  • /usage. Mostra onde você está na janela, antes de ser cortado no meio de uma refatoração.
  • grep antes de ler. Peça ao agente para achar o trecho e ler só a faixa de linhas, sem abrir o arquivo de 2 mil linhas.
  • Output pesado em arquivo. Mande o log do teste para um arquivo temporário e traga de volta só as falhas e a contagem.
  • Modelo menor no trabalho mecânico. Busca, checagem e renomeação não pedem o modelo mais forte. O caro fica para arquitetura e bug difícil.
  • Subagent para exploração ampla. Ele lê o repositório no contexto dele e devolve só o resumo ao seu. Para um lookup pequeno não compensa, porque o subagent começa do zero.

E no Antigravity?

A mecânica de contexto é a de qualquer agente sobre um LLM stateless: histórico reenviado, saída de ferramenta acumulando, sessão longa mais cara a cada passo. Limites e planos são outros, então consulte a documentação dele. O protocolo vale igual: uma tarefa por sessão, estado em arquivo, contexto pequeno.

O handoff em markdown também funciona entre ferramentas. Dá para começar a tarefa numa e retomar na outra, porque o estado está no arquivo e não na sessão.

O veredito

Limite de uso é orçamento de contexto, e orçamento se gerencia: aloca pouco, libera cedo, mede. Ninguém mantém uma conexão de banco aberta o dia inteiro "porque pode precisar". Abre, usa e devolve ao pool. Com sessão de agente vale o mesmo, e o recurso escasso é contexto.

Antes de pagar por um plano maior, rode /context na sessão mais longa que você tiver aberta e compare com o piso de uma sessão nova.

Gostou deste artigo? Compartilhe com outros desenvolvedores ou na sua rede.