Un mapa de código para agentes de IA es un índice local de los archivos, símbolos, imports, tests e historial de cambios de un repositorio que un agente puede consultar, de modo que encuentra el código correcto en unas pocas llamadas en lugar de hacer grep y leer archivo tras archivo. Menos archivos leídos significa menos en la ventana de contexto, y menos en la ventana de contexto significa que cada turno posterior sale más barato.
Este artículo explica por qué los agentes malgastan tokens explorando, qué contiene un buen mapa y cómo el mapa del proyecto de AgentVera da ese índice a Claude Code, Codex y otros agentes CLI por MCP.
Cómo explora un agente un repositorio sin mapa
Dale a un agente de programación una tarea como «añadir un campo de cupón al checkout» en un repositorio desconocido y hará lo que harías tú con solo una terminal:
grep -r "checkout"y obtener 200 resultados- Abrir los archivos que parecen prometedores, a menudo enteros
- Seguir los imports leyendo más archivos
- Buscar de nuevo el archivo de tests
Cada paso mete texto en el contexto. Un archivo de 1.000 líneas leído una vez queda en la conversación durante el resto de la sesión, y el modelo vuelve a leer la conversación en cada turno. Si las primeras suposiciones eran erróneas, esos archivos siguen ahí. Es una de las principales razones por las que una sesión se encarece mucho antes de que se haga el cambio real. Para la otra gran fuente, el contexto base, consulta cómo reducir el uso de tokens de Claude Code.
Qué contiene un mapa de código útil
Una lista de archivos no basta. Un agente necesita responder «dónde» y «qué se rompe si cambio esto» sin leer código. Un buen mapa contiene:
| Capa | Responde |
|---|---|
| Archivos y módulos | ¿Qué hay en este repositorio y cómo está organizado? |
| Símbolos con firmas | ¿Dónde está applyCoupon y qué recibe? |
| Imports | ¿Quién usa este archivo, y quién usa a esos? |
| Tests enlazados | ¿Qué tests cubren este código? |
| Historial de cambios conjuntos | ¿Qué archivos suelen cambiar junto con este? |
| Puntos de entrada y comando de test | ¿Por dónde empieza y cómo ejecuto los tests? |
Los dos últimos importan más de lo que parece. El historial de git sabe que checkout.ts, checkout.test.ts y pricing.ts suelen cambiar en el mismo commit, incluso cuando ningún import los une.
Cómo se construye el mapa del proyecto de AgentVera
AgentVera construye un mapa del proyecto para cada carpeta de proyecto:
- Símbolos. tree-sitter lee funciones, clases, métodos, interfaces, tipos, enums y constantes con rangos de líneas, firmas y la primera frase del comentario de documentación, para TypeScript, TSX, JavaScript, Python y Go. Otros 30 lenguajes más se indexan por ruta.
- Imports y tests. Los imports se resuelven a archivos, y los tests se enlazan con el código que cubren.
- Cambios conjuntos. Se enlazan los archivos que cambiaron juntos en al menos 2 de los últimos 500 commits. Los commits que tocan más de 40 archivos se ignoran, para que un gran renombrado no enlace todo con todo.
- Qué omite. Parte de
git ls-filesy respeta.gitignore. Omitenode_modules,dist,build, archivos de más de 1 MB y archivos generados o minificados. En repositorios con más de 20.000 archivos solo indexa carpetas de código fuente comosrc,lib,appypackages/*/src.
El mapa se construye en tu ordenador y no gasta tokens. Vigila los cambios en los archivos, recuenta el historial de cambios conjuntos cuando llegan commits y vuelve a comprobar un archivo cuando un agente pregunta por él. Un mapa por carpeta lo comparten todos los agentes que trabajan ahí, así que un proyecto y cada uno de sus worktrees tienen el suyo. Se guarda comprimido en la carpeta de datos de la app.
Las herramientas MCP que usan los agentes
AgentVera añade a cada agente un servidor MCP llamado agentvera-map. Sus instrucciones le dicen al agente que empiece una tarea con map_related, use map_outline antes de leer un archivo y map_usages antes de cambiar código.
| Herramienta | Devuelve |
|---|---|
map_related | Los archivos que probablemente implica una tarea, ordenados, con las razones (coincidencia de nombre, imports, cambios conjuntos, tests) |
map_outline | Los símbolos de un archivo con rangos de líneas y firmas, sus imports, quién lo importa y sus tests |
map_usages | Quién llama o importa un símbolo o archivo, a profundidad 2 los que importan a los importadores, más los tests que lo cubren |
map_find | Símbolos o archivos por nombre aproximado, con tipo, file:line y firma |
map_overview | Módulos, tamaños, puntos de entrada y el comando de test |
map_api | La API exportada real de un paquete instalado, en la versión de node_modules, a partir de sus declaraciones de tipos |
map_related acepta una tarea en lenguaje natural, en cualquier idioma. Palabras turcas como sepet, kupon u ödeme coinciden con nombres de código en inglés como cart, coupon y payment.
map_api corrige una fuente silenciosa de bugs: un agente que escribe llamadas de memoria para una versión de una librería que no tienes. Lee los archivos .d.ts de la versión realmente instalada.
Los agentes nuevos también reciben en sus instrucciones un breve resumen de los módulos, los puntos de entrada y el comando de test, para no gastar los primeros turnos averiguando cómo ejecutar los tests.
Antes y después: la misma tarea
Así cambia la tarea del cupón. Los pasos son típicos, no un benchmark.
Sin 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 testsCon el 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 testsDespués el agente lee solo las líneas que necesita. La primera versión llena el contexto con archivos que no necesitaba; la segunda lo llena con una lista ordenada y un esquema.
Smart tools: cuando el agente lee de todos modos
Los agentes no siempre consultan primero el mapa. Para Claude Code, las smart tools de AgentVera usan hooks para intervenir:
- La primera lectura completa de un archivo de más de 800 líneas y 24 KB devuelve en su lugar el esquema del mapa del proyecto, para que el agente pueda leer la parte que necesita.
- Las lecturas repetidas de un archivo que no ha cambiado se bloquean, porque el contenido ya está en el contexto.
- Las ejecuciones de tests se acotan a los tests que importan.
Si quieres ver cómo funcionan los hooks en general, lee la guía de hooks de Claude Code.
Activar y desactivar el mapa
El mapa del proyecto está activado por defecto y forma parte del plan gratuito.
- Abre Settings → Token savings y busca el interruptor Project map. Está activado salvo que lo hayas desactivado.
- Para dejar a un agente sin él, desmarca su casilla Project map en el diálogo de edición del agente.
- Para ver el mapa, abre la página Details del proyecto y la pestaña Project map. Dibuja un grafo con los imports en gris y los enlaces de cambios conjuntos como líneas naranjas discontinuas. Escribe una tarea y pulsa Show para ver lo que devolvería
map_related.
Si el mapa aún no está listo, por ejemplo justo después de abrir un repositorio grande, las herramientas responden con el progreso de la construcción. El agente espera unos segundos y después recurre a sus herramientas habituales.
¿De verdad ahorra tokens?
La respuesta sincera es: depende del repositorio y de la tarea. En un repositorio pequeño donde el agente ya sabe dónde mirar, se gana poco. En un repositorio grande o desconocido, donde un agente leería una docena de archivos equivocados, se gana mucho.
En lugar de fiarte de una cifra, mídelo en tu propio trabajo. La pestaña AI ROI tiene una tarjeta Project map impact que compara las conversaciones con y sin el mapa por éxito, aprobación a la primera, tokens por tarea y seguimientos.
Límites que conviene conocer
- El detalle de símbolos es para TypeScript, TSX, JavaScript, Python y Go. Los demás lenguajes reciben indexado a nivel de ruta.
- Los agentes en un host SSH remoto no reciben el mapa.
- Un agente solo lee el mapa de su propia carpeta, así que un agente de worktree ve su worktree, no el checkout principal.
- La ventana de mapa de código del recorrido del proyecto de AgentVera es una función aparte para que explores el código tú; el mapa del proyecto es lo que consultan los agentes.
Resumen
Un mapa de código para agentes de IA sustituye la exploración a ciegas de grep y lectura por unas pocas preguntas dirigidas: qué archivos, qué símbolos, quién los usa y qué tests los cubren. El mapa del proyecto de AgentVera construye ese índice en local con tree-sitter y git, lo mantiene al día y se lo da a todos los agentes con MCP a través de agentvera-map, mientras que las smart tools interceptan las lecturas grandes y repetidas en Claude Code. Combínalo con una memoria de proyecto compartida para que los agentes sepan tanto dónde está el código como por qué es así, y descarga AgentVera para probarlo en tu repositorio más grande.