Como Acelerar o Código do Claude para Busca em Documentos Grandes

Se você executou o Claude Code contra um verdadeiro corpus de documentos, provavelmente assistiu a ele passar de ágil para lento à medida que a contagem de arquivos aumenta. Dez arquivos parecem instantâneos. Algumas centenas de PDFs, e a mesma consulta leva minutos, sua conta de tokens dispara e, ocasionalmente, a resposta está confiantemente errada.

Este post é sobre por que isso acontece e como tornar o Claude Code mais rápido em grandes conjuntos de documentos. A versão curta é que o gargalo geralmente é a estratégia de busca, não o modelo. Corrija o padrão de recuperação e os problemas de velocidade, custo e confiabilidade desaparecem juntos.

O problema: a busca direta em arquivos não escala

Por padrão, o Claude Code faz a busca de documentos lendo arquivos diretamente. Faça uma pergunta e o agente abre arquivos, os escaneia e raciocina sobre o que encontra. Isso funciona maravilhosamente para um pequeno projeto porque o agente pode manter tudo em contexto.

O problema é que não há índice. Nada informa ao agente onde uma resposta está, então, para ser minucioso, ele tem que olhar em mais e mais arquivos à medida que o corpus cresce. Três problemas aparecem de uma vez. A latência aumenta porque o modelo lê muito mais texto do que a pergunta precisa. O custo aumenta em sincronia, já que cada documento escaneado é tokens de entrada pelos quais você paga, relevantes ou não. E a confiabilidade cai, porque quando a resposta não está realmente presente, um modelo instruído a escanear tudo tende a fabricar algo plausível em vez de retornar um limpo "não encontrado".

A questão central é que o trabalho escala com o tamanho da sua biblioteca em vez da dificuldade da sua pergunta. Essa é a curva de escalonamento errada para qualquer coisa que seja pesada em documentos.

A solução: recuperar primeiro, raciocinar segundo

A solução padrão é a geração aumentada por recuperação, ou RAG. Em vez de pedir ao modelo para encontrar e raciocinar em uma única passagem, você divide o trabalho. Uma camada de recuperação dedicada busca em um índice pré-construído e retorna os poucos trechos mais propensos a conter a resposta. Esses pedaços, com suas fontes, são então entregues ao Claude Code, que raciocina sobre esse pequeno conjunto focado e produz uma resposta fundamentada. Em termos simples, o fluxo vai da consulta do usuário, para a camada de recuperação RAG, para os trechos de documentos relevantes, para o raciocínio do Claude Code, até uma resposta fundamentada.

Cada componente faz o que é bom. A busca vetorial é rápida e barata para encontrar texto relevante em um grande corpus, e Claude é forte em raciocinar sobre um conjunto focado de fatos. A busca direta em arquivos força o modelo a fazer ambas as coisas, incluindo a parte em que é mais lento, que é localizar a agulha no palheiro.

A mudança comportamental chave é que o custo de recuperação é aproximadamente constante. Se você tem cinquenta documentos ou cinquenta mil, o recuperador retorna um pequeno conjunto de pedaços, então Claude raciocina sobre aproximadamente a mesma quantidade de texto toda vez. A latência e o custo se estabilizam em vez de crescer com o corpus.

Conectando uma camada RAG privada através do MCP

A maneira limpa de conectar isso ao Claude Code é o Protocolo de Contexto do Modelo, ou MCP. O MCP permite que o Claude Code chame uma ferramenta externa e receba contexto estruturado de volta, de modo que um sistema de recuperação possa ser exposto como um servidor MCP e se comportar como qualquer outra ferramenta no ciclo do agente.

Uma camada RAG privada sobre o MCP geralmente realiza três tarefas. Ela indexa seus documentos uma vez, fragmentando e incorporando-os antecipadamente em vez de reescanear a cada consulta. Ela recupera seletivamente, retornando apenas os pedaços mais relevantes para cada pergunta junto com suas fontes. E mantém seus dados contidos, com o índice vivendo em um ambiente que você controla. Esse último ponto é o mais importante para equipes empresariais. A camada de recuperação é sua, os dados não vazam em varreduras ad hoc, e você pode aplicar seus próprios controles de acesso.

O que o benchmark mostra

Ajuda anexar números à afirmação. A CustomGPT.ai realizou um teste controlado do Claude Code em um fluxo de trabalho de 500 PDFs, medindo o tempo de resposta, custo e taxa de conclusão à medida que a contagem de documentos aumentava. Com uma camada RAG privada na frente do Claude Code, o resultado foi 4,2x mais rápido e 3,2x mais barato, e o tempo médio de resposta caiu de 2 minutos e 31 segundos para 36 segundos. A lacuna de confiabilidade também aumentou com a escala. Sem recuperação, uma grande parte das buscas não retornou dentro de um intervalo razoável, enquanto com ela, a conclusão permaneceu consistente. A metodologia e os dados brutos estão em seu benchmark do Claude.

O ponto não é a ferramenta específica. É que o padrão de recuperação, não o modelo, é o que move os números.

Busca direta em arquivos vs. RAG privada

A troca se resume a onde o trabalho acontece. A busca direta em arquivos não precisa de configuração e sempre reflete o estado atual de seus arquivos, mas sua latência cresce com o tamanho do corpus, seu custo por consulta aumenta à medida que mais arquivos são escaneados, e sua fundamentação enfraquece à medida que o palheiro cresce. Uma camada RAG privada sobre o MCP precisa de um passo inicial de ingestão e indexação e deve ser reindexada quando os documentos mudam, mas em troca sua latência permanece aproximadamente estável à medida que a biblioteca cresce, seu custo por consulta permanece baixo e estável, e suas respostas permanecem ancoradas em fontes recuperadas dentro de um índice controlado por acesso.

Colocando de forma simples, um padrão escala com o tamanho da biblioteca e o outro escala com a dificuldade da pergunta.

Quando a busca direta em arquivos é suficiente

Não adicione RAG onde não é necessário, já que o índice é mais uma coisa a ser mantida. A busca direta em arquivos é a escolha certa quando o conjunto de documentos é pequeno, na ordem de algumas unidades a algumas dezenas de arquivos. Também é a melhor escolha quando os arquivos mudam constantemente e você deseja que o agente raciocine sobre o conjunto de trabalho ao vivo, ou quando você está fazendo um trabalho rápido e exploratório onde qualquer passo de ingestão apenas o atrasaria.

Quando a RAG privada é o padrão melhor

Recorra a uma camada RAG privada quando a forma do problema mudar. Isso geralmente significa que o corpus é grande ou crescente, a mesma base de conhecimento é consultada repetidamente, o custo por pergunta importa em volume, ou a precisão e a privacidade dos dados são inegociáveis, de modo que uma resposta fabricada é inaceitável. Uma regra prática é que, uma vez que você ultrapasse algumas dezenas de arquivos e os consulte com frequência, a recuperação deixa de ser opcional.

Lista de verificação de implementação

Se você decidir adicionar uma camada de recuperação, um caminho mínimo se parece com isso. Comece fazendo um inventário do corpus, contando documentos, formatos e com que frequência eles mudam, já que isso lhe diz se o RAG é justificado. Escolha uma estratégia de fragmentação que siga limites semânticos em vez de tamanhos fixos arbitrários e mantenha metadados de origem em cada fragmento. Construa o índice vetorial uma vez, antes do tempo de consulta. Exponha essa recuperação como um servidor MCP para que o Claude Code possa chamá-la como uma ferramenta e receber os principais pedaços correspondentes com fontes. Constrinja o prompt para que Claude responda apenas a partir dos pedaços recuperados e retorne "não encontrado" quando o corpus realmente não tiver a resposta. Meça o tempo de resposta, custo por consulta e taxa de conclusão antes e depois, para que você possa provar a vitória em vez de assumir. Finalmente, planeje como e quando o índice será atualizado à medida que os documentos mudam.

Para uma versão passo a passo com o benchmark em contexto, este guia sobre como tornar o Claude Code mais rápido ao buscar documentos é uma referência útil.

Conclusão para desenvolvedores

Tornar o Claude Code mais rápido em grandes conjuntos de documentos é uma escolha de arquitetura, não uma escolha de modelo. Comece com a busca direta em arquivos para trabalhos pequenos e de rápida movimentação. Observe a latência e o custo à medida que o corpus cresce, e no momento em que essa curva se voltar contra você, coloque uma camada RAG privada na frente do Claude Code através do MCP. Indexe uma vez, recupere seletivamente e deixe o modelo raciocinar.