Hay una frase que mucha gente piensa y muy poca dice en voz alta: no entiendo el código que escribí. La app funciona, la usa gente real, la construiste tú, y si abres cualquier archivo no puedes decir con seguridad qué hace ni por qué. Cada cambio es una apuesta. Cada bug es una excavación. Estás ejecutando un software que no entiendes, y eres tú todo el equipo de soporte.
Este es uno de los estados más comunes y menos hablados del software moderno. No es un defecto personal y no es permanente. Pero la salida no es la obvia, y la obvia te va a ahogar.
El plan obvio que fracasa
El instinto es: siéntate y léetelo entero hasta entenderlo. Línea a línea, archivo a archivo, hasta que encaje.
Esto fracasa por una razón concreta. El código generado por IA suele ser localmente razonable y globalmente disperso. Hay mucho, está repartido y fino, y leerlo de arriba abajo te da miles de detalles y ninguna estructura. Terminas más cansado y no más claro, porque entender software no es haber leído las líneas. Es conocer la forma: cuáles son las partes reales, cómo se conectan, dónde vive el comportamiento importante. Eso es una cosa distinta del texto, y leer el texto no te la entrega.
El segundo instinto que fracasa es reescribirlo, para al menos entender la versión nueva. Eso cambia una app que funciona y no entiendes por una app rota que sí entiendes, y reconstruye los mismos huecos por el camino. Casi nunca es la respuesta.
Qué significa entender de verdad
No necesitas conocer cada línea. Ningún ingeniero en activo conoce cada línea de un sistema del que es responsable. Lo que tiene es un mapa a la altura correcta, y la capacidad de hacer zoom cuando hace falta.
En concreto, tener el control de tu app significa que puedes responder, sin leer código:
- ¿Cuáles son las cuatro o cinco piezas reales de esta app, y para qué sirve cada una?
- Cuando un usuario hace lo principal, ¿qué pasa, en orden, a través de esas piezas?
- ¿Dónde vive el dato, y qué forma tiene?
- Si cambio esto, ¿qué más podría notarlo?
Ese es el objetivo. No fluidez en cada archivo. Un modelo navegable del conjunto, con el detalle disponible cuando lo necesitas y fuera de tu camino cuando no.
Cómo construir el mapa
Puedes hacer una versión de esto a mano hoy. Es lento, pero funciona, y vale la pena hacerlo al menos una vez para saber qué debe contener el mapa.
Empieza por fuera, no por el código. Lista lo que hace la app desde el punto de vista de un usuario. Las features, los flujos, los roles. Esta es la columna de la que colgarás todo lo demás.
Traza un flujo de principio a fin. Elige la única cosa más importante que hace un usuario. Síguela desde la pantalla hasta donde acaba el dato, nombrando cada parte por la que pasa. No leas nada que no tengas que leer. Estás dibujando la ruta, no inspeccionando el terreno.
Nombra las partes reales. Al final de un par de trazas, las mismas pocas piezas se repiten. Esas son tus partes reales. Escríbelas con una frase cada una. La mayoría de las apps tienen sorprendentemente pocas.
Pídele al agente que lo explique, y luego verifica. Puedes hacer que un modelo resuma un archivo o un flujo. Esto es genuinamente útil y genuinamente peligroso, porque un resumen plausible de código que hace otra cosa es peor que ningún resumen. Trata cada explicación como una afirmación que hay que comprobar contra el comportamiento, no como un hecho. Aquí aplica la misma disciplina de que un build en verde no es prueba: una explicación que suena bien no es lo mismo que una que está bien.
Cuando puedas bosquejar las partes y trazar el flujo principal de memoria, has pasado de pasajero a conductor. Sigues sin poder leer cada línea. Ya no lo necesitas.
Cuánto tiempo lleva esto en realidad
El rango honesto es más estrecho que los dos extremos que la gente teme. No es un arreglo de cinco minutos, y para la mayoría de apps que una persona todavía puede describir desde fuera, tampoco es una auditoría de varias semanas.
Trazar un flujo de principio a fin, la primera vez despacio, es una tarde: seguir desde la pantalla hasta el dato, nombrando cada parada por el camino, con el agente ayudándote a leer piezas que de otro modo tendrías que abrir en frío. Nombrar las partes reales, una vez que has trazado dos o tres flujos, va rápido, porque las mismas pocas piezas se repiten. Escribir una frase para cada una son minutos, no horas.
Lo que lo alarga no es la técnica. Es cuánto hace la app de verdad y cuántas de sus partes te sorprenden de verdad. Una app con cinco partes reales y un flujo principal es una tarde. Una app que ha hecho crecer en silencio quince piezas que nadie nombró nunca se acerca más a unas pocas sesiones repartidas en varios días, porque cada parte sorprendente exige su propia traza pequeña.
En cualquier caso, sale más barato de lo que parece antes de empezar, y solo se vuelve más caro cuanto más esperas, por la misma razón por la que el ajuste de cuentas del día 90 llega con calendario: el mapa que construyes hoy gasta memoria que todavía tienes. El que construyes en el mes cuatro es arqueología.
Escríbelo antes de que se te olvide otra vez
La parte cruel de este estado es que ya estuviste en él una vez, al principio, y se desvaneció. La comprensión que construyas ahora también se desvanecerá, a menos que viva en algún sitio fuera de tu cabeza. Así que mientras construyes el mapa, escríbelo: las partes, los flujos, para qué sirve cada uno. Este es el comienzo de la documentación que el prototipo nunca tuvo, y es lo que evita que aterrices otra vez aquí dentro de dos meses. Un mapa que solo vive en la memoria es un mapa que perderás, y por eso acaba queriendo convertirse en un mapa vivo del código, no prompts más largos que reescribes en cada sesión.
Esto es la etapa uno de un puente más largo
Volverse legible no es todo el trabajo, es su primera etapa. Una vez que puedes navegar la app, los movimientos siguientes son escribir qué se supone que hace, poner una red de seguridad bajo el comportamiento actual y reforzar la estructura, en ese orden. Entender es lo que hace posibles los tres: no puedes especificar, probar ni arreglar lo que no encuentras. La ruta completa desde aquí está en de vibe coding a producción.
Dónde encaja PaellaDoc
El mapa manual funciona una vez. El problema es que el código sigue cambiando y el mapa de tu cabeza se queda obsoleto de inmediato, que es como llegaste aquí. PaellaDoc lee un repo existente y lo convierte en un modelo navegable de sus partes y flujos reales, y mantiene ese modelo pegado al código a medida que cambia, para que el mapa siga siendo cierto en vez de pudrirse al día siguiente de dibujarlo. El objetivo no es leer el código por ti. Es que “qué hace esta app en realidad” tenga una respuesta que sobreviva más que tu memoria de haberla construido.
No estás atascado. Estás a un mapa de tener otra vez el control de tu propia app.
Preguntas frecuentes
¿Cómo entiendo código generado por IA que en realidad no leí? No leyendo cada línea. Construye un mapa al nivel de partes y flujos: cuáles son las piezas reales, cómo se mueve la acción principal del usuario a través de ellas y dónde vive el dato. Entender es conocer la forma, no haber leído el texto.
¿Debería reescribir código que no entiendo? Casi nunca. Una reescritura cambia una app que funciona y no entiendes por una rota que sí, y recrea los mismos huecos. Mapéalo y refuérzalo en su sitio.
¿Puedo simplemente pedirle a la IA que me explique el código? Como punto de partida, sí, pero trata cada explicación como una afirmación que verificar contra el comportamiento real. Un resumen seguro de código que hace otra cosa es peor que ninguno.
¿Necesito contratar a un desarrollador para construir este mapa? No para empezar. Listar las features desde fuera, trazar un flujo de principio a fin y nombrar las partes reales no requiere leer ni escribir código, solo seguir lo que hace la app y pedirle al agente que explique piezas sobre la marcha. Es más probable que quieras un desarrollador para la siguiente etapa, reforzar la estructura con tests y arquitectura, una vez que el mapa te haya enseñado qué sostiene peso de verdad.
¿Cuánto tiempo lleva construir este mapa en realidad? Para una app con un puñado de partes reales y un flujo principal, una tarde: trazar el flujo una vez, despacio, y luego nombrar las partes que se repiten. Se alarga a unas pocas sesiones en varios días solo cuando la app ha hecho crecer en silencio partes que nadie nombró nunca, porque cada sorpresa exige su propia traza pequeña. En cualquier caso sale más barato ahora que después, porque el mapa gasta memoria que todavía tienes.