Porque é que o Claude Code volta a ler o projeto inteiro e como resolver isso

Documentação da Ailoot: API, chaves e ligação.

Porque é que o Claude Code volta a ler o projeto do início de cada vez?#

Muitas pessoas pensam que isto é um erro. Na verdade, é assim que o Claude Code foi concebido: não tem um índice próprio do projeto. Quando lhe pede para corrigir algo, não tem à mão um mapa do código já preparado — explora novamente o projeto: encontra ficheiros relevantes, pesquisa as cadeias necessárias e lê os ficheiros para a memória.

Esta abordagem tem vantagens reais. O código está sempre atualizado — não há um índice desatualizado. Não há nada para configurar. O seu código não é enviado para nenhuma base de dados.

Mas também há uma desvantagem: cada nova tarefa implica uma nova ronda de pesquisa e leitura de ficheiros. Os tokens são gastos a descobrir novamente onde está cada coisa, apesar de o Claude já o ter apurado na sessão anterior. Quanto maior for o projeto, mais custa este reconhecimento. É precisamente este mecanismo que pode dar a sensação de que o agente está a «ler tudo».

Quantos tokens consome realmente?#

O custo começa antes do seu pedido. Uma medição independente mostra-o de forma simples: o Claude Code envia cerca de 33 000 tokens de prompt de sistema e descrições de ferramentas antes de ler o primeiro carácter da sua mensagem. Em comparação, o OpenCode começa com cerca de 7 000.

Depois entra em cena a releitura. Cada pesquisa e leitura de ficheiros acrescenta tokens ao contexto. A documentação oficial do Claude Code diz claramente: a leitura de ficheiros domina o consumo de contexto. Analisar auth.ts, com 2 400 tokens, significa que só o Claude vê esses 2 400 tokens; o mesmo se aplica a todos os ficheiros que abre durante o reconhecimento.

Para o nosso público, isto traduz-se em dinheiro e limites. O maior receio de quem começa a fazer vibe coding é: «Paguei e os limites esgotaram-se sem motivo.» Se o agente percorre o projeto e volta a ler os ficheiros do início em cada tarefa, o contexto esgota-se duas vezes mais depressa: primeiro com a sobrecarga do sistema e depois com o reconhecimento. No guia «Para onde vão os tokens do Claude Code», apresentei o mapa completo de onde são gastos exatamente os tokens do Claude Code — a releitura do projeto é um dos nove padrões aí descritos.

O que é a memória de código persistente?#

A memória de código resolve precisamente a lacuna que leva o Claude a voltar a ler o projeto. A ideia é simples: usar uma ferramenta para analisar todo o código uma vez, criar um mapa a partir dele e mantê-lo à mão. Assim, o agente não tem de pesquisar do zero de cada vez — consulta o mapa.

Tecnicamente, funciona assim. Uma ferramenta separada analisa o projeto e divide-o em componentes: que funções e classes existem, quem chama quem e que ficheiros estão ligados. Esta estrutura é guardada no disco. Quando o Claude precisa de perceber onde está a lógica de pagamentos ou o que poderá deixar de funcionar se uma função for editada, faz uma consulta direcionada ao mapa em vez de ler dezenas de ficheiros.

Este mapa é ligado através de MCP — a forma padrão de associar uma ferramenta externa ao Claude Code. No guia «Servidores MCP para o Claude Code», expliquei como ligar outros servidores. A ferramenta de memória de código acrescenta os seus próprios comandos de pesquisa no mapa, que o Claude utiliza por iniciativa própria quando precisa de se orientar no projeto.

Na prática, a diferença está entre «ler a pasta toda para encontrar uma função» e «perguntar ao mapa onde está essa função». A primeira opção custa dezenas de milhares de tokens; a segunda, centenas.

Duas abordagens à memória de código: em que diferem?#

As ferramentas de memória de código diferem naquilo que criam a partir do seu projeto. A forma mais simples de pensar nelas é: uma dá-lhe mãos de cirurgião para editar e a outra pesquisa por significado.

As contagens de estrelas no GitHub são de 15 de julho de 2026 (segundo a API do GitHub). As duas ferramentas são gratuitas e de código aberto, funcionam com o Claude Code e ligam-se como servidores MCP.

Em resumo, para quem não programa: a Serena é como uma mão de cirurgião: use-a quando edita a mesma parte ao longo do projeto e a precisão é importante. O claude-context é uma pesquisa por significado: encontra código a partir de uma descrição, mas exige configurar uma base de dados na cloud e uma chave.

Quando deve escolher a Serena ou o claude-context?#

As duas ferramentas não competem por um único prémio. Lembram-se de coisas diferentes, por isso a escolha depende da tarefa.

Escolha a Serena se fizer muitas refatorações. Dá ao agente uma navegação no código semelhante à de um ambiente de desenvolvimento inteligente: encontra a definição de uma função e todos os locais onde é realmente chamada e, em seguida, muda cuidadosamente o nome da função ou substitui o respetivo corpo em todo o projeto. O autor descreve assim a vantagem.

A Serena não publica uma percentagem exata de poupança, e não lhe vou atribuir um valor inventado. A vantagem é outra: uma pesquisa normal devolve quarenta correspondências, incluindo comentários e cadeias de texto, após o que o Claude lê quatro ficheiros inteiros; a Serena responde com algumas consultas precisas. Isso significa menos chamadas e menos correspondências falsas e, por conseguinte, menor risco de o agente editar a coisa errada.

Escolha o claude-context se precisar de pesquisa por significado e não se importar com a configuração. Converte o código em vetores (impressões digitais numéricas do significado) e pesquisa por descrição: «encontra onde está a nossa lógica de pagamentos», mesmo que não saiba os nomes das funções. O preço desta pesquisa é a configuração adicional.

O claude-context requer uma base de dados vetorial externa, uma chave de um fornecedor de embeddings e uma versão recente do Node. Das duas ferramentas, é a que exige mais trabalho para configurar, por isso recomendo que os principiantes comecem por outra.

O que pode fazer diretamente no Claude Code sem ferramentas de terceiros?#

Antes de instalar ferramentas de terceiros, tire o máximo partido do que o Claude Code já inclui. Estes comandos são gratuitos e funcionam de imediato.

1. /context — mostra uma discriminação em tempo real do que ocupa a janela: prompt de sistema, CLAUDE.md, memória, ferramentas e ficheiros. O comando /mcp mostra o custo de cada servidor ligado e /memory mostra o que foi carregado no arranque.
2. /compact — comprime o histórico da conversa num resumo curto e continua a mesma tarefa. Pode orientar o foco acrescentando ao /compact o que deve ser preservado.
3. /clear — elimina todo o histórico. A recomendação oficial é executá-lo ao mudar para uma tarefa sem relação com a anterior, para que a conversa antiga não ocupe o espaço dos ficheiros de que precisa.
4. /doctor (também conhecido como /checkup, introduzido a 8 de julho de 2026) — diagnostica a configuração e sugere correções: remove duplicados do CLAUDE.md, encontra ferramentas e servidores não utilizados e deteta processadores lentos.

Uma nota separada sobre o CLAUDE.md. Este ficheiro é carregado para o contexto no início de cada sessão e incluído em todas as mensagens. Se for demasiado extenso, continua a pagar por ele. A recomendação oficial é mantê-lo abaixo de 200 linhas e transferir os detalhes de referência para competências carregadas quando necessário. Expliquei como estruturar corretamente o CLAUDE.md no guia separado «Como configurar o CLAUDE.md».

Outra opção integrada são os subagentes. Têm o seu próprio contexto separado, pelo que pode delegar-lhes tarefas de leitura e reconhecimento mais exigentes sem sobrecarregar a janela principal. Na sua análise de engenharia, a Anthropic apresenta o princípio geral desta forma.

Um servidor MCP adicional aumenta ainda mais o contexto?#

A ideia de que «mais um servidor significa mais sobrecarga de contexto» costumava estar certa, mas o Claude Code mudou. As descrições das ferramentas MCP são agora carregadas de forma diferida por predefinição: no arranque, só os nomes dos servidores são incluídos no contexto, e as descrições completas são carregadas quando uma ferramenta específica é necessária para a tarefa. A documentação afirma-o claramente.

A lógica da memória de código é simples: uma pequena sobrecarga fixa pelos nomes das ferramentas, em troca de milhares de tokens poupados porque o agente deixa de voltar a ler os ficheiros. O saldo favorece claramente o índice.

Algumas ressalvas honestas, para não criar expectativas de magia. O índice precisa de ser reconstruído de vez em quando — o mapa reflete o código tal como estava no momento da análise e, depois de alterações importantes, tem de ser atualizado (isto varia consoante a ferramenta: algumas fazem-no automaticamente; outras requerem um comando). E afirmações impressionantes como «120 vezes menos tokens» descrevem o melhor cenário em consultas selecionadas, não o que verá em todas as tarefas. A poupança real é mais modesta, mas continua a ser percetível. Se quiser uma análise mais aprofundada sobre como evitar esgotar os limites em geral, tenho uma análise separada: «Como evitar esgotar os limites do Claude Code».

Por onde começar hoje?#

Se eliminar tudo o que é desnecessário, o plano para hoje é simples:

1. Execute /doctor e limpe o que este sugerir: duplicados no CLAUDE.md e ferramentas não utilizadas.
2. Reduza o CLAUDE.md a 200 linhas e transfira o material de referência para competências.

Depois, escolha de acordo com as suas necessidades: se fizer muitas refatorações, adicione a Serena para edições precisas; se precisar de pesquisa por significado, configure o claude-context. A memória de código e um contexto limpo resolvem hoje o principal problema.

Se precisar de acesso a modelos de IA através da Ailoot, consulte a Ailoot.