# Mapa do código para agentes de IA: ache código sem grep

URL: https://agentvera.dev/pt/blog/codebase-map-for-ai-agents/ · Publicado: 2026-10-24

Mapa do código para agentes de IA: como um índice local de arquivos, símbolos, imports e testes ajuda o Claude Code e o Codex a achar o código certo lendo menos.

**Resumo:**

- Sem um mapa, os agentes exploram com grep e lendo arquivos inteiros. Cada arquivo lido vai para a janela de contexto e é pago de novo a cada turno seguinte.
- O mapa de projeto do AgentVera indexa arquivos, símbolos, imports, testes ligados e arquivos que mudam juntos; é gerado localmente com tree-sitter, então não custa tokens.
- Os agentes consultam o mapa via MCP: map_related para os arquivos de uma tarefa, map_outline antes de ler, map_usages antes de mudar código, map_api para a API real de um pacote instalado.

**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:

1. `grep -r "checkout"` e recebe 200 resultados
2. Abre os arquivos que parecem promissores, muitas vezes inteiros
3. Segue os imports lendo mais arquivos
4. 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](/pt/blog/claude-code-token-usage/ "Reduza o uso de tokens do Claude Code em 61%").

## 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](/pt/features/project-map/ "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-files` e respeita o `.gitignore`. Pula `node_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 como `src`, `lib`, `app` e `packages/*/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:**

```text
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 tests
```

**Com o mapa:**

```text
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 tests
```

Depois 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](/pt/features/smart-tools/ "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](/pt/blog/claude-code-hooks-guide/ "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.

1. Abra **Settings → Token savings** e encontre a chave **Project map**. Ela fica ligada, a não ser que você a tenha desligado.
2. Para deixar um agente sem o mapa, desmarque a caixa **Project map** na janela de edição do agente.
3. 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_related` retornaria.

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](/pt/blog/shared-memory-for-ai-coding-agents/ "Memória compartilhada para agentes de código com IA") para que os agentes saibam tanto onde o código está quanto por que ele é assim, e [baixe o AgentVera](/pt/download/) para testar no seu maior repositório.

## Perguntas frequentes

**O que é um mapa do código para agentes de IA?** Um índice do repositório que o agente pode consultar em vez de procurar às cegas: quais arquivos existem, que símbolos eles definem, quem os importa, quais testes os cobrem e quais arquivos costumam mudar juntos.

**Um mapa do código reduz os tokens do Claude Code?** Pode reduzir. Cada arquivo que o agente lê fica no contexto e é relido nos turnos seguintes. Se o agente pede primeiro um outline ou uma lista ranqueada de arquivos, ele lê menos coisas e coisas menores. Quanto economiza depende do repositório e da tarefa.

**Quais linguagens o mapa de projeto do AgentVera entende?** Ele lê símbolos de TypeScript, TSX, JavaScript, Python e Go, com intervalos de linhas, assinaturas e a primeira frase do comentário de documentação. Cerca de 30 outras linguagens são indexadas pelo caminho.

**Gerar o mapa custa tokens?** Não. O mapa é gerado no seu computador com tree-sitter e git, e se mantém atualizado conforme os arquivos mudam e os commits chegam. Só as respostas que o agente pede entram no contexto dele.

**Quais agentes podem usar o mapa de projeto?** Todo agente CLI do AgentVera que aceita servidores MCP, como Claude Code, Codex, opencode, Copilot, Gemini e Cursor. Agentes num host SSH remoto não recebem o mapa.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/