Sacaste una app funcionando en un fin de semana. Un agente escribió casi todo, tú dirigías, la demo salió bien. Tres semanas después, un cambio de dos líneas te lleva un día entero y no tienes claro por qué la app sigue arrancando. Ese día que perdiste es el pago de intereses. Lo que no viste fue el momento en que pediste el préstamo.
Todo el mundo llama a esto deuda técnica. El nombre es correcto y también esconde algo. Cuando Ward Cunningham acuñó la deuda técnica, la deuda era código que entendías, escrito bajo presión, que decidías limpiar más tarde. El vibe coding produce otro animal: código que nunca leíste, generado a una velocidad que ninguna revisión humana siguió. Llamarlo un único bloque de “deuda” te dice que existe. No te dice qué debes ni cuándo llega la factura.
Así que déjame partirlo en las tres deudas que de verdad se comportan distinto.
La deuda no es un solo número
El error es tratar un código hecho con vibe coding como un único montón de atajos que ya limpiarás algún día. Ese marco te paraliza, porque “reescribirlo bien” nunca es la tarea del tamaño adecuado ni la semana adecuada para hacerla.
Las deudas que importan acumulan intereses a ritmos distintos y vencen ante disparadores distintos. Si sabes nombrarlas por separado, puedes pagar primero la cara y dejar en paz la barata. Ese es todo el movimiento.
Capa 1: deuda de comprensión
Es la que nadie contabiliza. Es la distancia entre lo que hace tu software y lo que sabes explicar de él.
Cuando escribes el código a mano, la comprensión viene gratis, como efecto secundario. Cuando lo escribe un agente, la comprensión es un coste aparte que has pagado o has aplazado. Casi todo el vibe coding lo aplaza entero. La app funciona, así que sigues adelante, y el modelo de cómo funciona no vive en ninguna parte salvo en un chat que se fue scroll arriba.
La deuda de comprensión es invisible hasta que necesitas cambiar algo. Entonces cobra intereses a un ritmo brutal, porque cada edición empieza con una sesión de arqueología. Estás haciendo ingeniería inversa de tu propio producto. Ese es el impuesto que hay detrás del miedo a tocar tu propio código: el miedo es racional, y es la deuda de comprensión pasándote la factura.
Lo peligroso es que compone en silencio. Cada feature que el agente añade encima de código que no entendías ensancha la brecha. Para el tercer mes ya no mantienes una app. Negocias con un desconocido que comparte tu repo.
Capa 2: deuda de tests y verificación
Es la deuda que sí se ve, y por eso justamente se confunde con el problema entero.
Las apps hechas con vibe coding suelen salir sin tests, o con tests que el agente escribió para describir lo que el código ya hace en vez de lo que debería hacer. En cualquiera de los dos casos, no tienes señal independiente de que la cosa funciona. Tienes el hecho de que funcionaba la última vez que hiciste clic por ahí, que no es la misma afirmación.
La deuda de verificación tiene una propiedad concreta y desagradable: se mantiene barata justo hasta que es catastrófica. Mientras nadie cambie nada, la ausencia de tests no cuesta nada. En el momento en que tú o un agente publicáis un cambio, los tests que faltan son la razón de que una feature rota llegue a un usuario antes de que te enteres. Ese es el mecanismo detrás de cada feature nueva que rompe una vieja: sin una capa de verificación no hay puerta entre “el agente dijo que funciona” y producción.
Hay una versión peor que no tener tests, que es tener tests que pasan sin demostrar nada. Un agente que informa de “todos los tests en verde” cuando la suite nunca ejecutó el camino que cambió te ha dado un recibo falso. Distinguir un pase real de un build verde que no verifica nada es su propia disciplina, y por eso un build en verde no es una feature correcta.
Capa 3: deuda de arquitectura
Es la más lenta y la más cara, y es de la que hablaba la metáfora original.
La deuda de arquitectura es estructural: lógica duplicada que debería ser una función, un modelo de datos que asumió un caso de uso y ahora sirve a cinco, fronteras que nunca se dibujaron, así que todo depende de todo. Los agentes son muy buenos produciendo esto, porque cada prompt es una optimización local. El agente resuelve bien el cambio que tiene delante y no tiene un modelo estable del sistema que está cambiando. El resultado es código localmente correcto y globalmente incoherente: cada pieza defendible, el conjunto derivando.
La deuda de arquitectura cobra el interés más alto de las tres, pero lo cobra tarde. Puedes funcionar sobre una mala arquitectura durante un tiempo sorprendentemente largo. Lo que te roba es tu velocidad futura. La app que tardó un fin de semana en construirse tarda un mes en ampliarse, y la razón nunca es un solo archivo malo. Es el coste acumulado de una estructura que nadie diseñó.
Cuándo vence cada una
Las deudas tienen fechas de vencimiento, y conocerlas es cómo dejas de pagar intereses por sorpresa.
La deuda de comprensión vence la primera vez que necesitas cambiar algo no trivial, que en un producto real suele ser dentro del primer mes. Es la factura más temprana y la más frecuente.
La deuda de verificación vence la primera vez que se publica un cambio que rompe algo que no tocaste. No puedes predecir la fecha, pero puedes tener la certeza de que existe, y aterriza más fuerte cuantos más usuarios tengas cuando lo haga.
La deuda de arquitectura vence cuando intentas escalar la app más allá de su forma original: una nueva integración, un segundo tipo de cliente, una feature que cruza otras tres. Es el rango de los 90 días donde las apps hechas con vibe coding tienden a romperse, no por un solo fallo sino porque las tres deudas vencen con semanas de diferencia entre sí.
Pagarla sin parar el mundo
Esto no se arregla reescribiendo. Se arregla pagando las deudas en el orden en que cobran intereses.
Paga primero la de comprensión, porque es la más barata de atender y todo lo demás depende de ella. Antes de tocar una feature, haz que el sistema se explique: qué hace este código, qué asume, qué se rompería si cambiara. No documentas por documentar. Recuperas el modelo que nunca construiste.
Paga la de verificación en segundo lugar, y págala con precisión. No necesitas cobertura total en un prototipo de fin de semana. Necesitas tests en los caminos que dolerían a un usuario si se rompieran, escritos antes de cambiarlos. Esa es también la respuesta real a cuándo añadir tests y arquitectura: ni el día uno, ni nunca, sino en el momento en que un camino pasa a sostener peso.
Paga la de arquitectura la última y solo donde te bloquee. Refactorizar código que no vas a cambiar es gastar dinero para reducir una factura que no te cobraba intereses. Reestructura la parte que amplías, deja el resto.
El hilo común es que las tres deudas son en realidad una sola cosa que falta: un registro duradero de intención y evidencia que viva fuera de la ventana de contexto del agente. Cuando ese registro no existe, cada cambio empieza de cero. Es el mismo fallo que hace imposible ascender un prototipo a producto sin un ajuste de cuentas doloroso.
Dónde encaja PaellaDoc
La razón de que el vibe coding produzca las tres deudas a la vez es que la comprensión del agente, el contrato de aceptación y la evidencia de lo que pasó se evaporan cuando termina la sesión. Nada sobrevive al chat.
PaellaDoc existe para mantener vivo ese registro en local: la intención detrás de un cambio, las decisiones que lo formaron, el código que tocó y la evidencia de que funcionó, conectados en un solo sitio en vez de repartidos por chats. No hace que la deuda desaparezca. Hace que la deuda sea legible, para que veas qué capa debes y la pagues a propósito, en lugar de descubrir el saldo por las malas, el día en que un cambio de dos líneas te cuesta una semana.
Preguntas frecuentes
¿La deuda técnica del vibe coding es peor que la normal? Es de otra forma. La deuda normal suele ser código que entendías y elegiste no limpiar todavía. El vibe coding añade encima deuda de comprensión: código que nunca leíste, así que debes entenderlo antes incluso de poder evaluar el resto.
¿Tengo que añadir tests a un proyecto de vibe coding de inmediato? No. Añádelos a los caminos que dolerían a un usuario si se rompieran en silencio, y añádelos antes de cambiar esos caminos. La cobertura total en un prototipo desechable es pagar una deuda que no te cobra intereses.
¿Cómo sé qué deuda pagar primero? Paga primero la de comprensión porque todo depende de ella, luego la de verificación en los caminos que sostienen peso, y la de arquitectura la última y solo donde bloquee el cambio que de verdad necesitas hacer.