Claude Code lento: como diagnosticar e acelerar suas sessões

Você pede uma correção pequena, mas o Claude Code passa minutos lendo pastas que não têm relação com o erro. Depois, a conversa fica pesada, o agente repete decisões antigas e a resposta final traz muito texto, mas pouca evidência de que a correção funciona.

Esse cenário costuma ser tratado como “o modelo está lento”. Na prática, as causas mais comuns são histórico acumulado, exploração ampla do repositório, saída de testes sem filtro e instruções que não deixam claro onde começar nem quando parar.

Neste guia, você vai diagnosticar a origem da lentidão antes de alterar o fluxo. O objetivo não é prometer um tempo universal, e sim reduzir trabalho desnecessário e medir a diferença no seu próprio projeto.

O que você vai ajustar

Identificar se o peso está no histórico, nas instruções, nas ferramentas ou na busca por arquivos.
Delimitar a tarefa sem retirar do Claude Code a informação necessária para trabalhar com segurança.
Usar /compact e /clear no momento certo, preservando decisões e erros ainda abertos.
Manter o CLAUDE.md curto e útil em todas as sessões.
Comparar um prompt amplo com outro delimitado, usando a mesma tarefa e o mesmo critério de aceite.

O Claude Code pode localizar arquivos, propor alterações, executar comandos autorizados e resumir evidências. A decisão sobre o comportamento esperado, o risco aceitável e a aprovação da mudança continua sendo humana. Velocidade não compensa uma correção que muda uma regra de negócio sem revisão.

Diagnostique antes de tentar acelerar

Comece com /usage. Para usuários da API, o comando mostra o consumo de tokens da sessão e uma estimativa local de custo. Para assinantes, mostra o uso do plano e sua atribuição. Use esse resultado como um indicador operacional; a cobrança oficial continua sendo a fonte final para valores faturados.

Em seguida, execute /context. Esse comando ajuda a enxergar quanto do contexto está ocupado por histórico, memória, servidores MCP, ferramentas e outras instruções carregadas. Se uma integração MCP ou um arquivo de memória ocupa grande parte do contexto desde o início, trocar de modelo não elimina a causa.

# Execute dentro do Claude Code antes de alterar o fluxo
/usage
/context
/compact Preserve arquivos alterados, testes com falha, decisões e perguntas em aberto

Use a tabela como roteiro de triagem:

Sintoma observado	Causa provável	Primeira ação
A sessão começa pesada	Memória, regras ou MCP carregados em excesso	Verifique `/context` e remova instruções permanentes desnecessárias
A lentidão aparece depois de várias tarefas	Histórico e logs acumulados	Use `/compact` com uma lista explícita do que deve permanecer
O agente lê dezenas de arquivos para um bug local	Prompt sem ponto de partida	Informe arquivos iniciais, teste relevante e pastas excluídas
A resposta demora após um teste	Saída extensa ou processo que não termina	Execute um teste específico e limite a saída preservando as linhas de erro
O agente volta a discutir decisões encerradas	Mudança de assunto no mesmo contexto	Use `/clear` ao iniciar uma tarefa sem relação com a anterior

Não use /compact como um botão automático de velocidade. A compactação resume o histórico; se você não disser o que precisa sobreviver, pode perder o comando que reproduz a falha ou o motivo de uma decisão técnica.

Adote um fluxo de trabalho rápido e previsível

Um fluxo simples reduz a variação entre sessões:

Defina o resultado esperado e o critério de aceite.
Aponte os primeiros arquivos e o teste que reproduz o problema.
Liste diretórios que não devem ser lidos sem necessidade.
Peça uma mudança por vez e solicite evidências no final.
Compacte ao encerrar uma fase; limpe o contexto ao trocar de assunto.

Este prompt mantém o escopo pequeno sem mandar o agente “corrigir rápido” às cegas:

claude -p "Corrija apenas o erro de verificação de valor nulo em src/api/auth.ts.
Leia primeiro src/api/auth.ts e tests/auth.test.ts.
Não examine node_modules, dist, coverage nem pastas de funcionalidades sem relação.
Execute o teste de autenticação e informe arquivos alterados, comandos executados e riscos restantes."

O ponto importante é combinar limite e evidência. “Leia apenas este arquivo” pode ser restritivo demais quando uma interface importada define o comportamento. “Comece por estes arquivos e peça autorização antes de ampliar o escopo” costuma ser uma instrução mais segura.

Mantenha apenas informações permanentes no CLAUDE.md

O CLAUDE.md deve conter fatos necessários em quase todas as sessões: comandos oficiais do projeto, mapa curto das pastas, regras de segurança e expectativas de verificação. Procedimentos raros, relatos antigos e instruções específicas de uma área aumentam o contexto de todas as solicitações, mesmo quando não ajudam.

Um arquivo inicial pode ser assim:

# CLAUDE.md

## Comandos do projeto
- Build: npm run build
- Testes: npm run test
- Verificação de tipos: npm run typecheck

## Navegação rápida
- API: src/api/
- Componentes de interface: src/components/
- Testes: tests/

## Não ler sem solicitação explícita
- node_modules/
- dist/
- coverage/
- .wrangler/

## Instruções para compactação
Ao compactar, preserve arquivos alterados, testes com falha, decisões, política de credenciais e próximas ações.

Revise esse arquivo como código. Quando uma regra deixa de ser válida, remova-a. Quando uma orientação só serve para um tipo de tarefa, mova-a para uma regra ou habilidade carregada sob demanda, em vez de transformá-la em custo permanente.

O CLAUDE.md orienta o comportamento do agente, mas não controla o acesso ao sistema. Uma linha como “não ler .env” ajuda a comunicar a política do projeto, porém não impede tecnicamente a leitura se o processo já tiver permissão para abrir o arquivo. Para impor limites, combine regras de permissão do Claude Code, hooks que bloqueiem ou validem chamadas de ferramentas, credenciais com privilégio mínimo e controles do sistema operacional ou do ambiente isolado. Segredos que o agente não precisa usar não devem estar disponíveis ao processo.

Meça a diferença com um teste pequeno

Não compare duas tarefas diferentes e conclua que o prompt mais curto foi melhor. Escolha uma correção reproduzível, mantenha o mesmo repositório e o mesmo critério de aceite, e execute uma rodada com instrução ampla e outra com escopo delimitado.

O script abaixo fixa o commit atual como base e cria uma worktree separada para cada variante. Assim, a segunda execução não herda arquivos modificados pela primeira. Ele mede o tempo e registra o código de saída e a quantidade de caminhos alterados; ainda é necessário comparar testes, arquivos lidos e qualidade da solução.

$repositorio = (git rev-parse --show-toplevel).Trim()
$fixture = (git rev-parse HEAD).Trim()
$raiz = Join-Path ([System.IO.Path]::GetTempPath()) "claude-benchmark-$([guid]::NewGuid())"

$execucoes = @(
  @{ Nome = "amplo"; Prompt = "Encontre e corrija o erro de autenticação neste projeto" },
  @{ Nome = "delimitado"; Prompt = "Corrija o erro de autenticação começando por src/api/auth.ts e tests/auth.test.ts. Execute o teste de autenticação e informe as evidências." }
)

New-Item -ItemType Directory -Path $raiz | Out-Null

foreach ($execucao in $execucoes) {
  $arvore = Join-Path $raiz $execucao.Nome
  $saida = Join-Path $raiz "$($execucao.Nome).txt"

  git -C $repositorio worktree add --detach $arvore $fixture | Out-Null
  if ($LASTEXITCODE -ne 0) {
    throw "Não foi possível criar a worktree $($execucao.Nome)."
  }

  try {
    $tempo = Measure-Command {
      Push-Location $arvore
      try {
        claude -p $execucao.Prompt *> $saida
      } finally {
        Pop-Location
      }
    }
    $codigoSaida = $LASTEXITCODE
    $caminhosAlterados = @(git -C $arvore status --porcelain).Count

    [pscustomobject]@{
      Nome = $execucao.Nome
      Fixture = $fixture
      Segundos = [math]::Round($tempo.TotalSeconds, 1)
      CodigoSaida = $codigoSaida
      CaminhosAlterados = $caminhosAlterados
      Log = $saida
    }
  } finally {
    git -C $repositorio worktree remove --force $arvore
  }
}

Execute o script a partir de um repositório Git limpo e escolha um commit que contenha uma falha reproduzível. As worktrees usam o mesmo commit, mas configurações externas, dependências ignoradas pelo Git, caches, rede e carga do serviço ainda podem variar. Mantenha também o mesmo modelo e as mesmas permissões. O resultado válido é a comparação feita no seu ambiente, acompanhada dos logs gravados em $raiz, não um valor copiado de outro projeto.

Três casos de uso práticos

Caso 1: corrigir um bug pequeno

Informe a mensagem de erro, o arquivo mais provável, o teste que falha e a condição de aceite. Peça ao agente que comece nesses pontos e justifique qualquer leitura adicional. Isso reduz a exploração sem impedir que ele siga uma dependência realmente necessária.

Exemplo de condição de aceite: “o teste tests/auth.test.ts deve passar e uma credencial ausente deve retornar 401, sem alterar o formato das respostas válidas”. A frase define comportamento observável; “faça o login funcionar” não define.

Caso 2: conduzir uma refatoração grande

Divida o trabalho em investigação, plano, alteração, teste e revisão. Ao fim de cada fase, use /compact preservando decisões, arquivos envolvidos, incompatibilidades e riscos. A sessão principal carrega conclusões; não precisa carregar todas as linhas de cada busca feita durante a investigação.

Se houver partes independentes, um subagente pode examinar testes ou mapear chamadas enquanto a sessão principal mantém a decisão arquitetural. Não delegue a dois agentes a edição do mesmo arquivo sem um responsável claro pela integração.

Caso 3: operar um pipeline de conteúdo ou tradução

Separe pesquisa, redação, localização e validação. Um agente pode trabalhar em um idioma específico, mas a sessão principal deve controlar fatos, links, critérios de qualidade e publicação. Enviar os dez idiomas e todos os logs de build para uma única conversa faz o contexto crescer sem melhorar a decisão editorial.

O mesmo princípio vale para geração de relatórios: envie ao agente as linhas relevantes e o caminho do arquivo completo, em vez de colar milhares de linhas na conversa. Preserve a mensagem de erro original para que a análise continue auditável.

Armadilhas que deixam a sessão mais lenta ou menos segura

Compactar sem instruções. A sessão fica menor, mas pode esquecer o teste que ainda falha. Corrija indicando arquivos alterados, decisões, comandos com falha e perguntas abertas.

Transformar o CLAUDE.md em arquivo morto. Cada incidente antigo vira contexto permanente. Corrija mantendo apenas instruções recorrentes e levando procedimentos específicos para regras ou habilidades acionadas quando necessário.

Retirar testes para economizar tempo. A resposta chega antes, mas o retrabalho aumenta. Corrija executando o menor teste que cobre a mudança e, depois, a verificação mais ampla exigida pelo projeto.

Limitar o escopo sem permitir exceções. Um erro local pode depender de um tipo ou configuração externa. Corrija pedindo que o agente comece nos arquivos indicados e relate por que precisa ampliar a leitura.

Colar logs completos. Saídas extensas consomem contexto e escondem a causa. Corrija filtrando o log, mas mantenha a primeira falha, a pilha relevante, o comando executado e o caminho para a saída completa.

Documentação oficial consultada

Para continuar a otimização, consulte também o guia de redução de tokens, o guia de permissões e a introdução à engenharia de infraestrutura para agentes.

Próximo passo

Escolha hoje uma tarefa pequena e repetível, execute o benchmark isolado e compare os dois logs junto com os testes. Se sua equipe precisa transformar esse diagnóstico em regras de projeto, limites de permissão e um fluxo de revisão comum, use a consultoria e o treinamento em Claude Code como próximo passo principal.

O que foi verificado na prática

Esta revisão não afirma um ganho percentual de velocidade, porque esse resultado depende do projeto e do ambiente. A sintaxe do exemplo PowerShell foi analisada sem iniciar duas sessões pagas do Claude Code. Também foram conferidos o uso de /usage, /context e /compact, a distinção entre orientação e controle de acesso no CLAUDE.md e o isolamento das duas variantes em worktrees criadas a partir do mesmo commit. Para obter um resultado no seu projeto, execute as duas rodadas, compare os logs, confirme os testes e registre o comportamento final, não apenas o tempo.