# Porque é que o Claude Code volta a ler o projeto inteiro e como resolver isso > O Claude Code não indexa o código e volta a ler o projeto do início, gastando tokens. Saiba como lhe dar memória de código persistente através de MCP e reduzir o consumo. Source: https://ailoot.ai/blog/pt-pt/claude-code-rereads-project/ Canonical: https://ailoot.ai/blog/pt-pt/claude-code-rereads-project/ Language: pt-PT Publisher: Ailoot (https://ailoot.ai/) Translation: guide-200 Revision: sha256-db4913af9e33ec2a747b8fb14787f12d28817cbe0455f20a12428c66ba97c3d7
Principal conclusão O Claude Code não mantém um índice do seu código. Em cada sessão, volta a pesquisar o projeto e lê os ficheiros do início, pelo que os tokens são gastos em reconhecimento em vez de trabalho. Pode resolver isto com memória de código: instale um servidor de indexação através de MCP e o Claude poderá usar um mapa do projeto já preparado, em vez de voltar a ler tudo.
[Documentação da Ailoot: API, chaves e ligação](https://ailoot.ai/docs/). ## Porque é que o Claude Code volta a ler o projeto do início de cada vez?
Principal conclusão O Claude Code não tem um índice de código integrado. Pesquisa o projeto com três ferramentas: encontra ficheiros por padrão, pesquisa cadeias de texto e lê ficheiros inteiros. A isto chama-se pesquisa agentic: o modelo decide onde procurar e repete o processo em cada nova tarefa. Não se lembra da sessão anterior, por isso cada nova sessão começa do zero.
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?
Principal conclusão Mesmo antes de voltar a ler o código, o Claude Code envia cerca de 33 000 tokens de dados de sistema em cada pedido. Numa configuração de trabalho real, o total chega aos 75 000–85 000 tokens antes de escrever uma única palavra. Depois, soma-se a releitura de ficheiros e, segundo a documentação oficial, a leitura de ficheiros é o que mais consome contexto.
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»](https://ailoot.ai/blog/pt-pt/where-claude-code-tokens-go/), 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?
Principal conclusão A memória de código é um mapa do projeto já preparado, que o agente pode consultar em vez de voltar a ler os ficheiros. Uma ferramenta separada analisa o seu código uma vez, cria uma estrutura de funções, ficheiros e ligações e guarda-a no disco. Mais tarde, quando pergunta «onde é tratado o pagamento?», o Claude obtém a resposta do mapa numa única consulta, em vez de percorrer todos os ficheiros.
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»](https://ailoot.ai/blog/pt-pt/mcp-servers-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?
Principal conclusão Há duas ferramentas úteis, ambas gratuitas ao abrigo da licença MIT. A Serena dá ao agente uma navegação no código semelhante à de um ambiente de desenvolvimento inteligente e é adequada para edições precisas. O claude-context pesquisa por significado através de embeddings, mas requer uma base de dados externa e uma chave. A diferença está naquilo de que cada ferramenta se lembra.
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. | O que comparamos | Serena | claude-context | |----|----|----| | Tipo de memória | Navegação no código através de um motor de ambiente de desenvolvimento | Pesquisa por significado através de embeddings | | O que encontra | Definições, locais reais de chamada, edições por símbolo | Código a partir de uma descrição: «onde está a lógica de pagamentos» | | Dependências externas | Gestor de pacotes uv; para TypeScript e JavaScript, também Node 20+ e npm | Base de dados externa + chave + Node 20+ | | Instalação | Um comando | Comando com três definições | | Poupança de tokens | Não publica uma percentagem exata | Cerca de 40% com qualidade equivalente | | Estrelas no GitHub | 26 468 | 12 138 | | Ponto forte | Refatoração cuidadosa em toda a base de código | Encontrar o que precisa sem conhecer os nomes exatos | | Ponto fraco | Menos linguagens, sem pesquisa por significado | Configuração complexa, requer um serviço na cloud | 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?
Principal conclusão A Serena é útil quando a precisão das edições é importante: mudar o nome de uma função em todo o projeto, substituir o respetivo corpo ou encontrar todos os locais onde é realmente chamada. Funciona através do mesmo motor utilizado por ambientes de desenvolvimento inteligentes e edita código pelo significado, não pela correspondência de texto. Escolha o claude-context quando precisar de pesquisar código por descrição e não se importar de configurar uma base de dados externa e uma chave.
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.

Um conjunto poderoso de ferramentas de código através de MCP: pesquisa e edição semânticas — um ambiente de desenvolvimento para o seu agente.

— Serena, https://github.com/oraios/serena
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.

Em média, o claude-context reduz o consumo de tokens em cerca de 40%, mantendo a mesma qualidade de pesquisa.

— zilliztech/claude-context, https://github.com/zilliztech/claude-context
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?
Principal conclusão Os comandos integrados resolvem metade do problema. `/context` mostra exatamente o que está a usar o contexto. `/compact` comprime o histórico, `/clear` reinicia-o antes de uma nova tarefa e `/doctor` encontra itens desnecessários e sugere a sua limpeza. Um ficheiro CLAUDE.md curto, em vez de um ficheiro excessivamente extenso, poupa milhares de tokens em cada mensagem.
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»](https://ailoot.ai/blog/pt-pt/claude-md-template/). 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.

Trabalhar bem com o contexto significa encontrar o menor conjunto possível de tokens ricos em informação que produza o resultado pretendido.

— Anthropic, https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
## Um servidor MCP adicional aumenta ainda mais o contexto?
Principal conclusão É uma preocupação legítima, mas não. Desde 2026, o Claude Code não carrega por predefinição as descrições completas das ferramentas MCP para o contexto — adia esse carregamento e só carrega o que for realmente necessário. No arranque, só os nomes são incluídos no contexto. Assim, um índice de código acrescenta uma quantidade insignificante de sobrecarga do sistema e poupa milhares de tokens que, de outra forma, seriam gastos a voltar a ler ficheiros.
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 pesquisa de ferramentas mantém baixo o consumo de contexto MCP, adiando as descrições das ferramentas até o Claude precisar delas. No arranque da sessão, só são carregados os nomes das ferramentas, pelo que adicionar servidores MCP quase não afeta a janela de contexto.

— Claude Code Docs, https://code.claude.com/docs/en/mcp
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»](https://ailoot.ai/blog/pt-pt/claude-code-token-limits-saving/). ## Por onde começar hoje?
Principal conclusão Comece pelo que é gratuito e rápido. Execute `/doctor` para limpar itens desnecessários. Reduza o CLAUDE.md a 200 linhas. Estes passos reduzem o que o Claude carrega para cada tarefa e começam a poupar os seus tokens e limites.
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.
### Fontes - [Serena, GitHub](https://github.com/oraios/serena) - [zilliztech/claude-context, GitHub](https://github.com/zilliztech/claude-context) - [Claude Code: janela de contexto, /compact, /clear, /context (documentação oficial)](https://code.claude.com/docs/en/context-window) - [Claude Code: ligação de MCP e pesquisa de ferramentas (documentação oficial)](https://code.claude.com/docs/en/mcp) - [Anthropic: engenharia de contexto eficaz para agentes de IA](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
Se precisar de acesso a modelos de IA através da Ailoot, consulte a [Ailoot](https://ailoot.ai/). ## Perguntas frequentes ### Quando escolho navegação por símbolos em vez de pesquisa de código por significado? Escolha navegação por símbolos, como Serena, para definições, locais de chamada e refatorização precisa. Pesquisa por significado, como claude-context, ajuda quando conhece o comportamento pretendido, mas não o nome do símbolo; exige configuração adicional de base de dados e embeddings. ### Posso continuar a confiar no mapa do código depois de alterar ficheiros? Verifique que o índice foi atualizado. Um mapa reflete o código analisado e a atualização difere consoante a ferramenta. Use o mapa para localizar o código pertinente e confirme depois os ficheiros atuais antes de os alterar. ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.