Como economizar 70% dos tokens do Claude com acesso pontual ao código

Um desenvolvedor escreveu uma ferramenta que economiza 70% da janela de contexto do Claude em projetos grandes. Em vez de ler arquivos inteiros, o agente de IA recebe acesso pontual ao código de que precisa, exatamente o que a tarefa exige.

O problema: o contexto, que é valioso, é desperdiçado

O Claude Code conhece a arquitetura do projeto pelo CLAUDE.md e entende quais arquivos são responsáveis por quê. Na prática, porém, o agente continua lendo arquivos inteiros. Se precisa de um único método, lê a classe inteira com todos os métodos. Se precisa descobrir onde uma função é chamada, lê diretório após diretório atrás de padrões. O contexto derrete e ainda não houve nenhum trabalho útil.

Um cenário típico: o desenvolvedor pede ao Claude que encontre um campo em uma entidade. O agente abre o arquivo inteiro, embora só as primeiras 20 linhas, com a descrição dos campos e o construtor, sejam necessárias. Ou, mais simples: é preciso entender a estrutura de relações entre as tabelas do banco de dados. O Claude lê arquivos SQL inteiros, quando os nomes das tabelas e as chaves bastariam para responder.

A janela de contexto é o principal recurso ao trabalhar com IA em projetos grandes. De 200K tokens, 100K podem ser gastos lendo código que poderia ser obtido de forma mais inteligente.

A solução: grafo de dependências e acesso pontual

O desenvolvedor escreveu dois scripts em PHP que funcionam juntos:

buildGraph.php varre o projeto uma vez e constrói um grafo de dependências em SQLite. Ele analisa código PHP e JavaScript e extrai classes, métodos, funções, importações e cadeias de herança. A execução é incremental: nas rodadas seguintes, atualiza apenas os arquivos que mudaram. Isso leva de 100 a 200 milissegundos em um projeto médio.

claudeSearch.php é uma interface CLI para agentes. Com um único comando, entrega ao Claude exatamente o que ele precisa:

• Um método específico de uma classe, com assinatura e corpo
• Todos os campos e o construtor de uma classe
• Toda a cadeia de herança de uma entidade
• Todas as consultas SQL a uma tabela específica
• A lista de todas as chamadas de uma função em todo o projeto
• Dependências entre módulos

Em vez de `Read(path/to/huge-file.php)`, o Claude agora escreve `search("User", "fields")` e recebe 15 linhas. Em vez de ler três diretórios, escreve `search("saveOrder()", "calls")` e vê todos os lugares em que esse método é usado.

Suporte a linguagens e velocidade

Por enquanto, a ferramenta tem suporte completo a PHP e JavaScript. O suporte a Go já foi adicionado. C virá depois.

A velocidade de análise é crítica: o grafo precisa ser atualizado pelo menos tão rápido quanto o desenvolvedor altera o código. A atualização incremental resolve o problema: a primeira rodada analisa o projeto inteiro (pode levar alguns segundos em um repositório grande) e as seguintes, em 100–200 ms, atualizam apenas os arquivos modificados.

O que isso entrega na prática

Segundo os cálculos do autor, a ferramenta reduz o consumo de tokens em 70% em um projeto médio típico. Isso não significa que cada requisição individual economize 70%, e sim que, ao longo de uma sessão de desenvolvimento, o contexto é usado três vezes mais eficientemente. Em vez de gastar 150K tokens lendo e depois 50K trabalhando, o desenvolvedor pode gastar 70K buscando e 80K trabalhando.

A ferramenta é especialmente útil para assistentes CLI e bots que não enxergam o sistema de arquivos por conta própria. Para eles, o grafo se torna a fonte da verdade sobre a estrutura do projeto.

O que isso significa

A ferramenta aponta uma direção: escalar o trabalho com o Claude em projetos grandes não depende só de decisões de arquitetura e de um CLAUDE.md bem escrito. É preciso ter acesso inteligente ao código. Leitura pontual em vez de leitura completa. Grafo em vez de sistema de arquivos. Quando o contexto vira uma limitação, é preciso ler com base no que realmente é necessário, e não na quantidade de código.