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 (programa que executa tarefas) quer descobrir onde algo acontece no código, costuma abrir um arquivo. Depois abre a pasta mais óbvia, um utilitário, um teste e outra pasta relacionada. Sem perceber, já gastou o contexto da sessão lendo código que não precisava para responder à pergunta.
Fiz isso por tempo demais. Parecia cuidadoso: ler mais para errar menos. Na prática, era uma forma cara de compensar a falta de um índice.
Isso acontece quando a pergunta não é "o que este arquivo faz?", mas "quem usa esta função (trecho de código que executa uma tarefa)?", "onde esta rota (caminho no sistema) é montada?" ou "qual componente (parte da interface) chama este hook (função reutilizada pelo código)?". Ler o repositório (pasta com os arquivos do projeto) inteiro é tratar uma pergunta sobre onde procurar como se fosse uma pergunta sobre o que o código faz.
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 lembra todo o repositório com precisão. Ele recebe algumas informações, usa-as por um tempo e, na sessão seguinte, repete a busca.
Ler arquivos também tira o foco. Quanto mais arquivos sem relação com a pergunta entram na sessão, mais a pergunta original compete com detalhes acidentais. Um nome parecido, uma função antiga ou um teste desatualizado pode levar o agente ao lugar errado.
O que um mapa guarda
Um mapa do código (índice que aponta onde cada parte está) não precisa guardar o código inteiro. Precisa mostrar nomes, arquivos, onde cada parte foi definida, quais outros arquivos ela usa e onde é usada. Para saber quem usa uma função, basta seguir essas relações. Não é preciso ler todos os arquivos linha por linha.
Um índice feito a partir da AST (estrutura que mostra como as partes do código se relacionam) ajuda nesse tipo de pergunta. Ele reconhece funções, métodos e chamadas dentro de componentes. Isso não substitui a leitura do arquivo quando chega a hora de mudar o comportamento. Mas evita que a primeira busca vire um passeio pelo repositório.
Eu separo assim: ler o código ajuda a decidir uma mudança. Consultar o mapa ajuda a decidir onde olhar. Misturar as duas tarefas encarece cada pergunta.
Comece por uma área
O erro seguinte é mapear a pasta principal inteira e chamar isso de contexto. Um índice de tudo fica grande demais para responder uma pergunta específica. Também pode ficar velho depressa. Qualquer mudança em qualquer lugar reduz a confiança no mapa inteiro.
Funciona melhor ter um mapa de uma área: um produto, parte do sistema, área do negócio ou camada. Se mexo na autenticação, não preciso carregar o mapa de marketing. Se mexo no blog, não preciso consultar o índice de faturamento.
Um mapa pequeno também é mais fácil de refazer quando muda. A consulta precisa ser barata e previsível. Atualizar o mapa pode levar mais tempo, desde que isso não aconteça enquanto alguém espera uma resposta.
Consultar não atualiza o mapa
Essa regra parece pequena, mas muda o sistema. Consultar o mapa nunca deve iniciar uma atualização. Se a primeira pergunta da sessão precisa esperar o índice ser criado, o índice virou outra forma de pedir "leia a pasta".
O mapa é preparado antes de alguém fazer uma pergunta. No fim de uma tarefa, atualizo a área afetada pelos arquivos que mudaram. Na sessão seguinte, a consulta só pergunta. Se o mapa não existe ou está velho, ele precisa dizer isso em vez de fingir precisão.
Depois disso, a leitura fica menor e mais intencional. O agente pergunta ao mapa por onde começar, abre poucos arquivos, confere a resposta no código real e só então edita. O mapa não decide a mudança. Só reduz a busca inicial.
Onde isso quebra
Um mapa desatualizado responde com a mesma confiança que um atualizado. Como a resposta chega rápido e organizada, pode parecer mais confiável que uma busca manual.
O risco é que um índice velho funciona como um comentário antigo. Não dá um erro claro. Ele aponta para o lugar errado, o agente abre o arquivo errado e o trabalho começa antes de alguém perceber.
Por isso, atualizo o mapa no fim da tarefa. Se o código muda e o mapa da área não é atualizado, é melhor ficar sem mapa. Um índice desatualizado troca leitura excessiva por certeza falsa.