# Mapa de código para agentes de IA: busca sin grep

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

Un mapa de código para agentes de IA: un índice local de archivos, símbolos, imports y tests ayuda a Claude Code y Codex a hallar el código leyendo menos archivos.

**En resumen:**

- Sin un mapa, los agentes exploran con grep y leyendo archivos enteros. Cada archivo leído entra en la ventana de contexto y se vuelve a pagar en cada turno posterior.
- El mapa del proyecto de AgentVera indexa archivos, símbolos, imports, tests enlazados y archivos que cambian juntos, y se construye en local con tree-sitter, así que no gasta tokens.
- Los agentes lo consultan por MCP: map_related para los archivos que toca una tarea, map_outline antes de leer, map_usages antes de cambiar código, map_api para la API real de un paquete instalado.

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

1. `grep -r "checkout"` y obtener 200 resultados
2. Abrir los archivos que parecen prometedores, a menudo enteros
3. Seguir los imports leyendo más archivos
4. 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](/es/blog/claude-code-token-usage/ "Reduce el uso de tokens de Claude Code un 61 %").

## 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](/es/features/project-map/ "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-files` y respeta `.gitignore`. Omite `node_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 como `src`, `lib`, `app` y `packages/*/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:**

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

**Con el 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
```

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

1. Abre **Settings → Token savings** y busca el interruptor **Project map**. Está activado salvo que lo hayas desactivado.
2. Para dejar a un agente sin él, desmarca su casilla **Project map** en el diálogo de edición del agente.
3. 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](/es/blog/shared-memory-for-ai-coding-agents/ "Memoria compartida para agentes de programación con IA") para que los agentes sepan tanto dónde está el código como por qué es así, y [descarga AgentVera](/es/download/) para probarlo en tu repositorio más grande.

## Preguntas frecuentes

**¿Qué es un mapa de código para agentes de IA?** Un índice de un repositorio que un agente puede consultar en lugar de buscar a ciegas: qué archivos existen, qué símbolos definen, quién los importa, qué tests los cubren y qué archivos suelen cambiar juntos.

**¿Un mapa de código reduce los tokens de Claude Code?** Puede hacerlo. Cada archivo que lee un agente permanece en su contexto y se vuelve a leer en los turnos siguientes. Si el agente pide primero un esquema o una lista de archivos ordenada, lee menos cosas y más pequeñas. Cuánto ahorra depende del repositorio y de la tarea.

**¿Qué lenguajes entiende el mapa del proyecto de AgentVera?** Lee símbolos de TypeScript, TSX, JavaScript, Python y Go, con rangos de líneas, firmas y la primera frase del comentario de documentación. Otros 30 lenguajes más se indexan por ruta.

**¿Construir el mapa gasta tokens?** No. El mapa se construye en tu ordenador con tree-sitter y git, y se mantiene al día a medida que cambian los archivos y llegan commits. Solo las respuestas que pide un agente entran en su contexto.

**¿Qué agentes pueden usar el mapa del proyecto?** Todos los agentes CLI de AgentVera que admiten servidores MCP, como Claude Code, Codex, opencode, Copilot, Gemini y Cursor. Los agentes en un host SSH remoto no lo reciben.

---

**Sobre AgentVera.** AgentVera es una app de escritorio para macOS, Windows y Linux, desarrollada por Solviera Teknoloji. Ejecuta 18 agentes de programación con IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) en paralelo, por proyecto, en terminales reales con las instalaciones y sesiones de CLI del propio usuario. El plan gratuito tiene agentes ilimitados. Descargar: https://agentvera.dev/es/download/ · Precios: https://agentvera.dev/es/pricing/