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