Um mapa do código vale mais que ler o código
Abrir a pasta inteira para responder onde algo acontece parece completo, mas vira um custo fixo. Um mapa pequeno por escopo responde melhor.
Quando um agente quer descobrir onde uma coisa acontece no código, a resposta mais comum é abrir arquivo. Primeiro a pasta óbvia, depois um utilitário, depois o teste, depois outra pasta que parecia relacionada. Quando percebe, a sessão já gastou contexto lendo código que não precisava estar ali para responder à pergunta original.
Eu fiz isso por tempo demais. Parecia prudente: ler mais para errar menos. Na prática, era uma forma cara de compensar a falta de índice.
O problema concreto aparece quando a pergunta não é "o que este arquivo faz", mas "quem usa esta função", "onde esta rota é montada", "qual componente chama este hook". Ler o repositório inteiro para isso é tratar uma pergunta de navegação como se fosse uma pergunta de interpretação.
O custo de ler a pasta
Pedir "leia a pasta" tem um custo escondido: você paga de novo em cada sessão. O agente não acorda lembrando todo o repositório com fidelidade. Ele recebe contexto, usa aquilo por um tempo, e depois a próxima sessão repete o mesmo ritual.
O custo não é só token. É foco. Quanto mais arquivo irrelevante entra na janela, mais a pergunta original concorre com detalhe acidental. Um nome parecido, uma função antiga, um teste desatualizado. O agente passa a ter material suficiente para montar uma resposta plausível em cima do lugar errado.
O que um mapa guarda
Um mapa de código não precisa guardar o código inteiro. O que eu quero dele é mais seco: símbolo, arquivo, definição, importação, chamada. Se a pergunta é "quem usa esta função", a resposta vem da relação entre símbolos, não da leitura linha a linha dos consumidores.
Um índice por AST resolve melhor essa classe de pergunta porque enxerga estrutura, não texto solto. Ele sabe que um nome é uma função, que outro é um método, que uma chamada está dentro de um componente. Isso não substitui a leitura do arquivo quando chega a hora de alterar o comportamento, mas impede que a busca inicial vire uma excursão pelo repositório.
A distinção que organiza tudo é esta: ler código é para decidir mudança; consultar mapa é para decidir onde olhar. Misturar as duas coisas torna toda pergunta cara.
Escopo antes da raiz
O erro seguinte é tentar fazer um mapa da raiz inteira e chamar isso de contexto. Um índice de tudo vira outro objeto grande demais para caber na pergunta. Ele também envelhece rápido, porque qualquer mudança em qualquer canto ameaça a confiança do conjunto.
O que funciona melhor é mapa por escopo. Um produto, um módulo, uma área de domínio, uma camada. Quando estou mexendo em autenticação, não preciso carregar o mapa de marketing. Quando estou mexendo em blog, não preciso que o índice me conte sobre faturamento.
O escopo pequeno tem outra vantagem: dá para reconstruir sem cerimônia quando muda. A consulta precisa ser barata e previsível. A reconstrução pode ser mais cara, desde que não aconteça no meio da pergunta.
Consulta não reconstrói
Essa regra parece detalhe, mas muda o sistema: consultar o mapa nunca dispara reconstrução. Se a primeira pergunta de uma sessão precisa esperar o índice nascer, o índice virou outra forma de "leia a pasta".
O mapa é preparado fora do caminho quente. No fim de uma tarefa, quando arquivos mudaram, o escopo afetado é atualizado. Na próxima sessão, a consulta só pergunta. Se o mapa não existe ou está velho, ele deve dizer isso em vez de fingir precisão.
Depois disso, a leitura fica menor e mais intencional. O agente pergunta ao mapa onde começar, abre poucos arquivos, confirma a interpretação no código real, e só então edita. O mapa não decide a mudança. Ele corta a parte burra da navegação.
Onde isso quebra
Mapa desatualizado responde com a mesma confiança que mapa atualizado. E como a resposta vem rápida, limpa e formatada, ela parece mais confiável do que uma busca manual bagunçada.
Esse é o risco real: índice velho é a versão silenciosa de comentário desatualizado. Ele não falha alto. Ele aponta para o lugar antigo, deixa o agente abrir o arquivo errado, e a sessão inteira anda alguns passos antes de alguém perceber.
Por isso a atualização precisa estar no fim da tarefa. Se mudar código e não atualizar o mapa do escopo, melhor não ter mapa. Um índice que não acompanha o trabalho não reduz custo; ele só troca leitura excessiva por certeza falsa.