Indexar o código fora do repo: como economizar tokens sem jogar o projeto no contexto

Pessoal, o agent precisava achar um símbolo. Trabalho de um minuto. Na prática, ele abria arquivo atrás de arquivo, colava dump de teste no papo e a janela sumia. Às vezes a fatura também.

Não era o modelo burro. Era eu pagando o monorepo inteiro pra responder a pergunta errada.

A pergunta mudou. Deixei de ser “qual tool faz o agent entender o repo?” e virei: o que é memória de domínio, e o que é só custo de ler código nesta sessão?

Tem um segundo motivo, e ele não é economia. Um índice de símbolos é um mapa do seu sistema: quem chama o quê, onde está o fluxo crítico. Se esse mapa mora no git, no cache de CI ou num serviço que o agent também escreve, o blast radius não é só token. É superfície.

Duas contas, um prompt

Memória de domínio é política. O que pode ser lembrado, por qual porta se entra, o que é canônico. Notas, contratos, “onde a gente decide X”. Indexer de código não resolve isso.

Code-read barato é custo de sessão. Achar caller e símbolo sem despejar o working tree no prompt. Isso não deveria virar a sua base de conhecimento.

Eu misturava. O indexer virava KB. O vault virava grep sem porta. Os dois falhavam, e a sessão inchava igual.

Economizar token aqui não é trocar de modelo da semana. É separar camada. E decidir onde o mapa vive.

O que eu mudei na mesa

O mapa de símbolos saiu do working tree. Cache local, fora do repo, fora do git. Reindex é operação de máquina, não de PR. O agent consulta o índice; não precisa reler o monorepo pra “quem chama essa função?”.

Quatro perguntas que eu faço antes de indexar um repo (vale colar no README do setup):

1. O índice vive na minha máquina ou sai dela (cloud, CI, cache compartilhado)?
2. Entra em contexto de agent que também tem tool de escrita?
3. Como eu apago e revogo?
4. Quem mais lê isso?

Índice ≠ fonte de verdade versionada. Least privilege no que entra no contexto continua valendo.

Depois, parei de mandar firehose de CLI cru. test, build, git status viram novela. Aquilo no contexto é fogo amigo. Output barulhento: comprimo com um wrapper de CLI, ou faço Read cirúrgico. Incidente que precisa da linha exata do log: aí sim firehose.

Por último: um code-read por sessão. Empilhar dois indexers dilui ROI e confunde o agent. Escolhe um. Se não servir, troca. Não some.

Índice também envelhece. Sintoma: o agent cita símbolo que não existe mais, com confiança. Aí reindexa. Sem isso, você só mudou o tipo de alucinação.

O que isso ainda não é

Isso não substitui contrato de memória. Hubs, scopes, “não responda só com grep” são outra conversa.

E uma honestidade: eu não tenho “economizei X% de tokens”. Sem medição, sem %. O que eu tenho é sessão menos inchada e um mapa que não vai parar no PR por acidente.

Artefato

## Token layers (coding agent)

1. Memória de domínio tem dono próprio. Indexer não é KB.
2. Índice de símbolos: fora do repo, fora do git.
3. Antes de indexar: onde vive, quem lê, o agent escreve, como revoga.
4. Um code-read por sessão. Não empilhe indexers.
5. CLI barulhento: comprime ou lê o trecho. Firehose só se a linha importa.
6. Índice velho: reindexa quando o agent citar o que não existe mais.

Regra de bolso: se a sessão está cara e você não sabe qual camada inchou, nomeie a camada antes de plugar mais tool.

Pergunta pra comunidade

No seu setup o índice é local (reindex chato, mapa em casa) ou hospedado (mais rápido, mapa fora da sua máquina)?

O que você não abre mão — e o que você cortaria primeiro: índice, dump de CLI, ou memória misturada com code-read?