Por qué tu agente de código con IA alucina rutas de archivo

La señal delatora no es un cuerpo de función incorrecto. Es una edición segura de sí misma a un archivo que no existe, o a un archivo que existe pero no es el que implementa el comportamiento.

Pediste una corrección de expiración de sesión. El agente abrió src/auth/session.ts. Esa ruta es plausible. También está mal. El handler real vive en apps/api/src/middleware/expiry.ts, renombrado hace dos refactorizaciones. El agente no te mintió. Completó una cadena con forma de ruta a partir de priors de entrenamiento más lo que ya hubiera en la ventana de contexto.

Este es el modo de fallo común en un repositorio real. El modelo sabe escribir código. El error está en elegir el lugar equivocado para escribirlo.

Por qué los agentes inventan rutas

Un agente de código es un modelo de predicción del siguiente token con herramientas. Cuando dices «arregla la expiración de sesión», tiene que nombrar un archivo antes de poder leer o parchear nada. Si todavía no tiene un mapa fundamentado, construye una ruta a partir de:

1. Convenciones de nombres que ha visto en otros repositorios. src/auth/session.ts es una forma frecuente.
2. Archivos que ya están en la conversación, que quizá sean los que pegaste la semana pasada, no los que importan ahora.
3. Listados de directorios que ejecutó por casualidad, incompletos en un árbol grande.
4. Archivos de instrucciones. CLAUDE.md y AGENTS.md le dicen al agente cómo comportarse. No son un índice vivo de símbolos, llamadores o rutas actuales.

Ninguna de esas fuentes es un mapa de este repo, hoy. El modelo llena el vacío como llena cualquier vacío: con una continuación de alta probabilidad. Esa continuación a menudo se ve como una ruta real. A veces el archivo existe y está junto al correcto. A veces existió en una rama que se fusionó el mes pasado. A veces nunca existió.

Grep no te salva aquí si el agente nunca busca la cadena correcta. El agente adivinó una ruta, luego leyó lo que esa ruta devolvía, luego la editó. El primer paso equivocado fue la ruta, no el parche.

Leer archivos tampoco es lo mismo que encontrar los correctos. Claude Code, Cursor, Codex y herramientas similares pueden abrir lo que sea que les señales. La pregunta es si encuentran de forma fiable los archivos correctos, los símbolos importantes, las dependencias, las pruebas y el radio de impacto antes de editar. El acceso a archivos sin un mapa sigue empezando con una suposición.

La edición del archivo equivocado es un problema de recuperación

Trata la ruta inventada como un fallo de recuperación, no como un defecto de personalidad.

Si el agente tuviera que devolver path/file.ext:line antes de que se le permitiera editar, sucederían dos cosas. Primero, podrías abrir la cita y rechazar el trabajo en diez segundos. Segundo, el agente tendría que consultar algo que realmente conoce el árbol.

Ese es el trabajo de una capa de contexto de código. La búsqueda semántica sola no basta. Un fragmento que «suena a expiración de sesión» puede aterrizar igualmente en un paquete obsoleto. También necesitas texto exacto cuando conoces la cadena, búsqueda de símbolos cuando conoces el nombre, búsqueda estructural cuando conoces la forma, y un grafo de dependencias cuando necesitas llamadores y radio de impacto.

Maguyva es esa capa para agentes de código compatibles con MCP. No es un editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf y otros clientes MCP se quedan donde están. El agente consulta un mapa clasificado antes de tocar una línea.

La afirmación es modesta a propósito: menos ediciones alucinadas. Maguyva no le quita al modelo la capacidad de adivinar. Cambia el primer paso por defecto de «inventar una ruta plausible» a «pedir ubicaciones clasificadas y citadas».

Cómo se ve una respuesta fundamentada

Una respuesta útil a «dónde se gestiona la expiración de sesión» no es un párrafo. Es una lista corta de ubicaciones:

• apps/api/src/middleware/expiry.ts:48 - el handler
• apps/web/src/lib/auth-client.ts:112 - el llamador
• apps/api/tests/expiry.test.ts:20 - la prueba que fallará si el cambio está mal

Puedes abrir esas líneas. Si están mal, te detienes. Si están bien, el agente puede editar. La verificación es el punto, no un eslogan.

Maguyva expone 11 herramientas MCP de cara al cliente en búsqueda, símbolos, análisis de dependencias, recuperación de archivos, contexto de repositorio y flujos de trabajo utilitarios deterministas. Cuatro modos de recuperación (semántico, estructural, grafo/dependencia y texto) se fusionan en resultados clasificados; la búsqueda de símbolos es una herramienta MCP separada (find_symbol). Las respuestas fundamentadas vuelven con rutas de archivo y números de línea, así que puedes evaluarlas contra el árbol que tienes delante.

Los docs describen el camino más corto: empezar gratis, indexar un repo que ya conoces, conectar el cliente, luego hacer una pregunta que puedas verificar.

Un bucle que cambia la primera edición

No necesitas una nueva religión de flujo de trabajo. Necesitas un paso extra antes de la primera escritura.

1. Haz una pregunta que ya puedas evaluar. «¿Qué código gestiona el inicio de sesión y la expiración de sesión?» es mejor que «arregla la autenticación».
2. Exige citas. Ruta de archivo y número de línea, no un resumen de «el módulo de autenticación».
3. Abre los archivos citados. Sigue el símbolo. Confirma la dependencia que estás a punto de tocar.
4. Solo entonces dejas que el agente parchee.

Si el paso 2 no devuelve nada útil, el agente no tiene permiso para improvisar una ruta. Busca de nuevo, o tú se lo indicas. Esa única barrera es lo que produce menos ediciones alucinadas. El modelo es el mismo modelo. El mapa es lo que cambió.

Los archivos de instrucciones siguen importando. Consérvalos. Úsalos para convenciones, reglas de revisión y lo que no hay que tocar. No les pidas que sean el índice. Un CLAUDE.md que lista tres directorios importantes quedará obsoleto la semana siguiente a una división de paquete. Un mapa consultable se actualiza cuando el repo se actualiza.

Un fallo relacionado es el archivo casi-correcto: el agente abre auth.ts cuando el comportamiento vive en auth-client.ts, o parchea un archivo generado en lugar de la fuente, o edita la copia en packages/legacy porque el nombre coincidía. Las citas no hacen esos errores imposibles. Los hacen visibles antes de que el diff aterrice.

Lo que un mapa no arreglará por ti

Sé claro sobre lo que estás obteniendo. Un mapa fundamentado no hará correcta cada edición — tu agente puede seguir escribiendo un mal parche en exactamente el archivo correcto. Si tu base de código se apoya en despacho dinámico, reflexión o monkey-patching, algunas búsquedas de símbolos volverán más pobres de lo que te gustaría, porque eso es lo que la indirección en tiempo de ejecución le hace a cualquier índice estático. Y si esperas un porcentaje — «rutas alucinadas reducidas en X%» — no lo encontrarás aquí, porque nadie puede medir honestamente esa cifra para tu repo salvo tú.

Lo que puedes esperar es más estrecho y más útil: el agente deja de abrir sus ediciones con una ruta adivinada. Ese primer paso queda fundamentado en un mapa real, y de ahí vienen las menos ediciones alucinadas. Todo lo que viene después de la cita — leer el diff, juzgar el parche — sigue siendo tu trabajo, igual que siempre lo fue.

La prueba casi no te cuesta nada: indexa un repo que ya conoces y haz una pregunta que puedas verificar. Empieza con una ruta con la que ya te hayan quemado antes. Si las citas están mal, lo verás de inmediato. Si están bien, la siguiente edición de tu agente tiene un lugar mejor donde aterrizar.

// it doesn't know the file. it knows how to find it.