Mapas del código, no prompts más largos

Le das al agente una tarea en una parte del codebase que no conoce. Se equivoca. Así que haces lo natural: escribes un prompt más largo. Describes la arquitectura, nombras los módulos importantes, explicas que la lógica de pagos vive aquí y la de reintentos allá, y de paso pegas un par de ficheros clave. El agente se equivoca un poco menos, rompe otra cosa, y mañana escribes un prompt aún más largo.

Hice esto durante semanas antes de ver la forma que tenía. El prompt no dejaba de crecer y los fallos no dejaban de moverse. Estaba tratando un problema estructural como si fuera de redacción, y ninguna cantidad de mejor redacción cierra un hueco estructural.

El agente no necesita más palabras sobre el codebase. Necesita un mapa de él. No son lo mismo, y esa diferencia es el punto entero de esta pieza.

Un prompt es prosa. Un mapa es estructura.

Esto es lo que es de verdad un prompt de arquitectura largo desde el lado del modelo: un muro de texto que tiene que leer, aguantar en la ventana de contexto, y del que tiene que re-derivar la estructura cada vez. Escribiste “el OrderService llama a InventoryService antes de escribir”. Eso es una frase. Para que el agente la use, tiene que parsear la frase en una relación, recordar la relación, y rezar para que mencionaras todas las demás relaciones que importan. Casi nunca lo haces, porque escribes desde tu propio mapa mental y te saltas las partes que te parecen obvias.

Un mapa es esa estructura entregada directamente. OrderService llama a InventoryService. Esa arista es un hecho que el agente puede consultar, no una frase que tiene que interpretar. No compite por espacio en la ventana de contexto con la tarea de verdad. No depende de que te acuerdes de mencionarla. O está en el mapa o no está, y si el mapa se construye desde el código, está.

Por eso los prompts más largos chocan pronto contra un techo. La prosa no compone. Cada frase que añades es más que leer y más que potencialmente contradecir. La estructura sí compone: mil aristas en un mapa le cuestan al agente casi nada hasta que consulta las diez que necesita.

Context engineering para agentes de código es en buena parte esta misma constatación aplicada de punta a punta: la victoria no es llenar más la ventana, es poner la estructura correcta donde el agente pueda alcanzarla.

Qué contiene de verdad un mapa del código

“Mapa” no es una metáfora de “buena documentación”. Es una cosa concreta. Un mapa del código útil lleva, como mínimo:

• La estructura de llamadas. Qué llama a qué. Es la columna vertebral. La mayoría de los errores peligrosos de un agente son cambios que ignoran un llamador, y la estructura de llamadas es justo el conjunto de aristas que le habría avisado.
• La estructura de dependencias. Qué importa qué, qué depende de qué servicio o tabla. Así es como el agente sabe si un cambio está contenido o si un cambio cruza medio sistema.
• El flujo de tipos y datos. Qué tipos fluyen por qué caminos. Renombra un campo y esto es lo que le dice al agente cada sitio donde ese campo se desempaqueta, no solo dónde se define.
• Las fronteras. Dónde acaba un módulo y empieza otro, y qué pocas funciones los puentean. Los agentes que respetan las fronteras escriben cambios que encajan con la forma existente en vez de perforarla.
• Los puntos de entrada. Endpoints, jobs, comandos de CLI, manejadores de eventos. Los sitios donde la ejecución de verdad empieza, para poder trazar un camino desde un disparador real hasta su efecto.
• Alcanzabilidad. Qué está vivo y qué está muerto. Un mapa que sabe que nadie llama a una función es un mapa que deja al agente dejar de preocuparse por ella.

Nada de eso es prosa que escribes. Todo es estructura que lees del código. El mapa es una proyección del sistema, que es también por lo que no envejece como envejece un documento de arquitectura escrito a mano. Cuando el código cambia, el mapa se regenera desde el código nuevo, y vuelve a ser verdad sin que nadie se acuerde de actualizarlo.

Por qué “usa un modelo más grande” también falla

El otro reflejo, al lado del prompt más largo, es esperar al modelo más grande. Seguro que un agente más listo con más contexto se apañaría con la estructura.

Se apaña con más parte de ella, y sigue empezando cada sesión desde cero. Una ventana de contexto más grande es más sitio donde pegar ficheros; no es un mapa, porque el modelo sigue teniendo que reconstruir las relaciones desde el texto pegado en cada ejecución. Estás pagando, en tokens y en tiempo, por reconstruir la misma estructura que el código ya contiene, una y otra vez, y rezando por que la reconstrucción esté completa esta vez. Normalmente no lo está, porque las relaciones que te rompen son las no obvias, y esas son justo las que una lectura desde cero tiene más probabilidad de saltarse.

Entrégale el mapa al modelo y el modelo listo se vuelve más listo, porque gasta su capacidad en la tarea en vez de en re-derivar el terreno. Ese es el sentido literal de la frase: mapas del código, no prompts más largos. La palanca se movió del tamaño del input a la forma de él.

El rename que un mapa habría cazado

Hazlo concreto. Le pides a un agente que renombre un campo de un struct central, userId a accountId, un cambio que parece trivial. Sin mapa, el agente hace grep de userId, encuentra la definición y los usos obvios del mismo módulo, los actualiza, y canta hecho. Se dejó el serializador de otro paquete que lee el campo por clave de texto, la migración SQL que nombra la columna, y un fixture de test tres directorios más allá que hardcodea el nombre viejo. El build incluso pasa, porque el fallo del serializador solo aparece en runtime contra datos reales. Te lo encuentras en producción, o lo encuentra un revisor después de una hora de lectura.

Con el mapa, el rename empieza distinto. El agente consulta al grafo todo lo conectado a ese campo: cada función que lo lee o escribe, cada tipo por el que fluye, cada test que toca esas funciones, los nodos de config y migración que lo referencian. Obtiene el conjunto completo antes de cambiar una línea, lo actualiza todo o te dice qué partes no puede tocar con seguridad, y el cambio aterriza entero. La diferencia nunca fue la inteligencia del modelo con el rename. Fue si el modelo podía ver el vecindario del campo. Un prompt más largo habría descrito el módulo que ya conocías y aun así se habría dejado el serializador, porque también te habrías olvidado de mencionarlo. El mapa no se olvida, porque no está recordando. Está leyendo.

Dónde encaja PaellaDoc

Esta es una de las razones por las que PaellaDoc lee tu repo a un grafo en tu máquina antes de que un agente lo toque. El mapa, la estructura de llamadas, las dependencias, las fronteras, los enlaces del código a las decisiones que lo pidieron, se construye desde el código real y se mantiene al día según el código se mueve. Los agentes lo consultan en vez de releer el mundo desde un prompt. Esa misma estructura es la que le deja a un grafo de conocimiento de producto responder preguntas un nivel más arriba, sobre forma y validación en vez de llamadas y tipos. Misma técnica, dos alturas.

La próxima vez que un agente se equivoque en código que no conoce, resiste el prompt más largo. Pregúntate qué relación le faltaba, y si esa relación vive en algún sitio que pueda consultar. Si no vive, ninguna frase que añadas la va a poner ahí. Un mapa sí.

↓ Descargar PaellaDoc · macOS

¿Cuál es el prompt más largo que has escrito intentando explicarle un codebase a un agente? Cuéntame en el foro.

Preguntas frecuentes

¿Por qué mi agente se equivoca una y otra vez en código que no conoce?

Normalmente porque le falta un mapa de la estructura, no porque tu prompt sea corto. Hace grep, lee unos ficheros e infiere las relaciones que importan, y se salta las no obvias, como un llamador en otro paquete. El fallo es estructural, y ninguna cantidad de mejor redacción cierra un hueco estructural.

¿Qué es un mapa del código?

No es buena documentación. Es la estructura leída del código: la estructura de llamadas (qué llama a qué), la de dependencias, el flujo de tipos y datos, las fronteras entre módulos, los puntos de entrada y la alcanzabilidad. Como es una proyección del código, se regenera cuando el código cambia en vez de envejecer como un doc de arquitectura escrito a mano.

¿Por qué un prompt más largo no arregla los fallos del agente?

Porque la prosa no compone. Cada frase es más que leer, más que potencialmente contradecir, y estructura que el modelo tiene que re-derivar en cada run, y te saltas las aristas que te parecen obvias. Un mapa entrega la estructura como hechos consultables, así que mil aristas cuestan casi nada hasta que el agente consulta las diez que necesita.

¿Un modelo más grande resuelve el código que no conoce?

Se apaña con más parte y sigue empezando cada sesión desde cero, reconstruyendo las relaciones desde el texto pegado en cada run. Las relaciones que te rompen son las no obvias que una lectura desde cero tiene más probabilidad de saltarse. Entrégale el mapa y gasta su capacidad en la tarea en vez de en re-derivar el terreno.