Um mapa do código para agentes de IA é um índice local dos arquivos, símbolos, imports, testes e histórico de mudanças de um repositório que o agente pode consultar, para achar o código certo em poucas chamadas em vez de fazer grep e ler arquivo após arquivo. Menos arquivos lidos significa menos coisa na janela de contexto, e menos coisa na janela de contexto significa que cada turno seguinte sai mais barato.
Este post mostra por que os agentes gastam tokens explorando, o que um bom mapa contém e como o mapa de projeto do AgentVera entrega esse índice ao Claude Code, ao Codex e a outros agentes CLI via MCP.
Como os agentes exploram um repositório sem mapa
Dê a um agente de código uma tarefa como “adicionar um campo de cupom no checkout” num repositório desconhecido, e ele faz o que você faria tendo só um terminal:
grep -r "checkout"e recebe 200 resultados- Abre os arquivos que parecem promissores, muitas vezes inteiros
- Segue os imports lendo mais arquivos
- Procura de novo pelo arquivo de teste
Cada passo puxa texto para o contexto. Um arquivo de 1.000 linhas lido uma vez fica na conversa pelo resto da sessão, e o modelo relê a conversa a cada turno. Se os primeiros palpites estavam errados, esses arquivos continuam lá. Esse é um dos principais motivos de uma sessão ficar cara muito antes de a mudança de fato ser feita. Para a outra grande fonte, o contexto base, veja reduzir o uso de tokens do Claude Code.
O que um mapa do código útil contém
Uma lista de arquivos não basta. O agente precisa responder “onde fica” e “o que quebra se eu mudar isto” sem ler código. Um bom mapa guarda:
| Camada | Responde |
|---|---|
| Arquivos e módulos | O que tem neste repositório e como ele está organizado? |
| Símbolos com assinaturas | Onde está applyCoupon e o que ela recebe? |
| Imports | Quem usa este arquivo, e quem usa esses? |
| Testes ligados | Quais testes cobrem este código? |
| Histórico de mudanças em conjunto | Quais arquivos costumam mudar junto com este? |
| Pontos de entrada e comando de teste | Por onde começa e como eu rodo os testes? |
As duas últimas importam mais do que parece. O histórico do git sabe que checkout.ts, checkout.test.ts e pricing.ts costumam mudar no mesmo commit, mesmo quando nenhum import os liga.
Como o mapa de projeto do AgentVera é gerado
O AgentVera gera um mapa de projeto para cada pasta de projeto:
- Símbolos. O tree-sitter lê funções, classes, métodos, interfaces, tipos, enums e constantes com intervalos de linhas, assinaturas e a primeira frase do comentário de documentação, para TypeScript, TSX, JavaScript, Python e Go. Cerca de 30 outras linguagens são indexadas pelo caminho.
- Imports e testes. Os imports são resolvidos para arquivos, e os testes são ligados ao código que cobrem.
- Mudanças em conjunto. Arquivos que mudaram juntos em pelo menos 2 dos últimos 500 commits ficam ligados. Commits que mexem em mais de 40 arquivos são ignorados, para que um grande rename não ligue tudo com tudo.
- O que fica de fora. Ele parte do
git ls-filese respeita o.gitignore. Pulanode_modules,dist,build, arquivos acima de 1 MB e arquivos gerados ou minificados. Em repositórios com mais de 20.000 arquivos, indexa só pastas de código comosrc,lib,appepackages/*/src.
O mapa é gerado no seu computador e não custa tokens. Ele acompanha as mudanças de arquivos, recalcula o histórico de mudanças em conjunto quando chegam commits e confere de novo um arquivo quando um agente pergunta sobre ele. Um mapa por pasta é compartilhado por todos os agentes que trabalham nela, então um projeto e cada uma das suas worktrees têm o seu próprio. Ele fica armazenado compactado na pasta de dados do app.
As ferramentas MCP que os agentes usam
O AgentVera adiciona a cada agente um servidor MCP chamado agentvera-map. As instruções dele dizem ao agente para começar uma tarefa com map_related, usar map_outline antes de ler um arquivo e map_usages antes de mudar código.
| Ferramenta | Retorna |
|---|---|
map_related | Arquivos que uma tarefa provavelmente envolve, ranqueados, com os motivos (nome parecido, imports, mudanças em conjunto, testes) |
map_outline | Os símbolos de um arquivo com intervalos de linhas e assinaturas, os imports, quem o importa e os testes |
map_usages | Quem chama ou importa um símbolo ou arquivo, com profundidade 2 quem importa quem importa, mais os testes que cobrem |
map_find | Símbolos ou arquivos por nome aproximado, com tipo, file:line e assinatura |
map_overview | Módulos, tamanhos, pontos de entrada e o comando de teste |
map_api | A API exportada real de um pacote instalado, na versão que está em node_modules, a partir das declarações de tipos |
map_related recebe uma tarefa em palavras comuns, em qualquer idioma. Palavras em turco como sepet, kupon ou ödeme casam com nomes em inglês no código, como cart, coupon e payment.
map_api resolve uma fonte silenciosa de bugs: o agente escrevendo chamadas de memória para uma versão de biblioteca que você não tem. Ele lê os arquivos .d.ts da versão que está de fato instalada.
Agentes novos também recebem nas instruções um resumo curto dos módulos, pontos de entrada e do comando de teste, para não gastarem os primeiros turnos descobrindo como rodar os testes.
Antes e depois: a mesma tarefa
Veja como a tarefa do cupom muda. Os passos são típicos, não um benchmark.
Sem mapa:
grep -rn "checkout" src # 200 lines of hits
cat src/checkout/index.ts # whole file
cat src/checkout/summary.tsx # whole file, not the right one
cat src/pricing/total.ts # whole file
grep -rn "total(" src test # find callers and testsCom o mapa:
map_related "add a coupon field to checkout"
-> src/pricing/total.ts (name match, changed together with checkout)
-> src/checkout/CheckoutForm.tsx (imports total.ts)
-> test/pricing/total.test.ts (test)
map_outline src/pricing/total.ts # symbols and lines only
map_usages calculateTotal # callers and testsDepois o agente lê só as linhas de que precisa. A primeira versão enche o contexto com arquivos desnecessários; a segunda, com uma lista ranqueada e um outline.
Smart tools: quando o agente lê mesmo assim
Os agentes nem sempre consultam o mapa primeiro. Para o Claude Code, as smart tools do AgentVera usam hooks para intervir:
- A primeira leitura completa de um arquivo com mais de 800 linhas e 24 KB devolve o outline do mapa de projeto, para o agente ler só a parte de que precisa.
- Leituras repetidas de um arquivo que não mudou são bloqueadas, já que o conteúdo já está no contexto.
- As execuções de teste são restritas aos testes que importam.
Se quiser entender como os hooks funcionam em geral, leia o guia de hooks do Claude Code.
Ligando e desligando o mapa
O mapa de projeto vem ligado por padrão e faz parte do plano gratuito.
- Abra Settings → Token savings e encontre a chave Project map. Ela fica ligada, a não ser que você a tenha desligado.
- Para deixar um agente sem o mapa, desmarque a caixa Project map na janela de edição do agente.
- Para ver o mapa, abra a página Details do projeto e a aba Project map. Ela desenha um grafo com os imports em cinza e as ligações de mudanças em conjunto como linhas laranja tracejadas. Digite uma tarefa e pressione Show para ver o que o
map_relatedretornaria.
Se o mapa ainda não estiver pronto, por exemplo logo depois de abrir um repositório grande, as ferramentas respondem com o progresso da geração. O agente espera alguns segundos e depois volta às ferramentas normais.
Economiza tokens de verdade?
A resposta honesta é: depende do repositório e da tarefa. Um repositório pequeno, em que o agente já sabe onde procurar, ganha pouco. Um repositório grande ou desconhecido, em que o agente leria uma dúzia de arquivos errados, ganha muito.
Em vez de confiar num número, meça no seu próprio trabalho. A aba AI ROI tem um card Project map impact que compara conversas com e sem o mapa por sucesso, aprovação na primeira tentativa, tokens por tarefa e mensagens de acompanhamento.
Limites que você precisa conhecer
- O detalhe de símbolos vale para TypeScript, TSX, JavaScript, Python e Go. As outras linguagens são indexadas no nível do caminho.
- Agentes num host SSH remoto não recebem o mapa.
- Um agente lê só o mapa da própria pasta, então um agente numa worktree vê a worktree dele, não o checkout principal.
- A janela de mapa do código no tour do projeto do AgentVera é um recurso separado, para você explorar o código; o mapa de projeto é o que os agentes consultam.
Resumo
Um mapa do código para agentes de IA troca a exploração às cegas com grep e leitura por algumas perguntas certeiras: quais arquivos, quais símbolos, quem os usa e quais testes os cobrem. O mapa de projeto do AgentVera gera esse índice localmente com tree-sitter e git, o mantém atualizado e o entrega a todo agente compatível com MCP pelo agentvera-map, enquanto as smart tools seguram leituras grandes e repetidas no Claude Code. Combine-o com uma memória de projeto compartilhada para que os agentes saibam tanto onde o código está quanto por que ele é assim, e baixe o AgentVera para testar no seu maior repositório.