Deuda técnica: qué es y cómo pagarla

La deuda técnica es el costo futuro que aceptas cuando entregas código que es más rápido de escribir ahora pero más difícil de cambiar después. Igual que la deuda financiera, no es mala de por sí. Se vuelve un problema cuando los intereses crecen más rápido que el producto. Aquí, los intereses son el tiempo extra que exige cada cambio.

Soy un ingeniero sénior brasileño que ha heredado bases de código y ha liderado una migración con el sistema en vivo. Esta guía se enfoca en lo que les importa a fundadores y CTOs: qué deuda ignorar, cuál pagar primero y cuándo parchar deja de tener sentido.

Puntos clave

• La deuda es un costo sobre los cambios futuros, no una medida de código feo. El código que nadie toca casi no cuesta nada.
• La deuda peligrosa está en los caminos del dinero (registro, checkout, facturación) y en el proceso de build y despliegue.
• Puedes medir la deuda sin herramientas especiales: el tiempo para entregar un cambio pequeño, el historial de incidentes y las áreas que nadie se atreve a tocar.
• Prioriza por los intereses que pagas, no por cuánto te molesta. Paga la deuda donde de todos modos vas a trabajar.
• Moderniza en lugar de parchar cuando la deuda está en los cimientos y cada funcionalidad tiene que pelear contra ella.

¿Qué es la deuda técnica?

La metáfora suele atribuirse a Ward Cunningham, que la usó a principios de los años noventa. La usó para explicar por qué entregar una primera versión imperfecta del código puede ser una decisión razonable, siempre que vuelvas y corrijas lo que aprendiste.

En la práctica, la deuda técnica se manifiesta en unas pocas cosas concretas:

• Atajos tomados para cumplir un plazo y nunca revisados.
• Frameworks, librerías o runtimes desactualizados que ya no reciben actualizaciones de seguridad.
• Falta de pruebas, así que nadie está seguro de que un cambio sea seguro.
• Falta de documentación, así que el conocimiento vive en la cabeza de una sola persona.
• Decisiones de diseño que tenían sentido para diez usuarios y duelen con diez mil.

Fíjate en lo que no está en la lista: el código que simplemente no te gusta. Las preferencias de estilo no son deuda. La deuda siempre tiene un precio que puedes describir en tiempo, riesgo o dinero.

¿Qué causa deuda técnica en un producto en crecimiento?

La mayor parte de la deuda no es culpa de malos ingenieros. Viene de decisiones razonables tomadas bajo presión y de que el producto cambia por debajo del código.

Atajos deliberados

Un equipo se salta las pruebas o deja una regla fija en el código para cumplir con una fecha de lanzamiento. Es el tipo sano de deuda si alguien la anota y planea volver. Se vuelve tóxica cuando se olvida.

Requisitos que cambian

El producto pivota, pero el modelo de datos y los nombres siguen describiendo el negocio anterior. Cada nueva funcionalidad tiene que traducir entre la idea vieja y la nueva.

Rotación y traspasos

Cuando una agencia o un desarrollador se va, las razones detrás de las decisiones se van con ellos. La siguiente persona parcha alrededor de lo que no entiende, lo que agrega otra capa de deuda.

Actualizaciones descuidadas

Las dependencias envejecen. Saltarse las actualizaciones menores durante dos años convierte una tarea pequeña en un proyecto riesgoso, y los intereses se acumulan en silencio.

Velocidad sin barandas

Prototipar rápido, incluso con código generado por IA, está bien para aprender. La deuda se acumula cuando el prototipo se convierte en el producto sin pruebas, sin control de acceso y sin una etapa de revisión.

¿Cómo distinguir la deuda inofensiva de la que bloquea el negocio?

Hazte una pregunta: ¿qué pasa si dejamos esto como está otros seis meses? Si la respuesta es nada, es inofensiva. Si la respuesta es un roadmap más lento, una caída del servicio o una exposición de seguridad, está bloqueando.

El patrón es que la deuda se vuelve peligrosa cuando se cruza con el cambio, el dinero o la seguridad. La deuda en un rincón tranquilo es ruido de fondo. La deuda en un pasillo con mucho tránsito es un peligro.

¿Cómo medir la deuda técnica en una base de código heredada?

Rara vez obtienes un número limpio, y yo desconfiaría de cualquier herramienta que diga dártelo. Lo que sí puedes obtener es un conjunto de señales que, juntas, te dicen qué tan caro es convivir con el código. Cuando me hago cargo de una base de código, trabajo en este orden: primero los accesos, luego el build, luego los caminos del dinero y luego los riesgos. Medir la deuda encaja en la misma secuencia.

Señales que vale la pena recopilar

• Tiempo para entregar un cambio pequeño. Suele ser lo primero que cronometro. Elige una tarea trivial, como cambiar una etiqueta o agregar un campo, y mide el tiempo desde el ticket hasta producción. Los tiempos largos apuntan a deuda en el build, las pruebas o el despliegue.
• ¿Puedes compilarlo y correrlo desde cero? Si una máquina nueva no puede correr el proyecto siguiendo el README, hay conocimiento oculto.
• Historial de incidentes y bugs. ¿Qué archivos o funcionalidades aparecen una y otra vez? Los reincidentes son donde los intereses son más altos.
• Puntos calientes de cambio. El historial del control de versiones muestra qué archivos cambian más. Los archivos que cambian seguido y se rompen seguido son tus principales candidatos.
• Mapa del miedo. Pregúntale al equipo qué partes evita tocar. Es subjetivo, pero sorprendentemente preciso.
• Estado de las dependencias y del runtime. Haz una lista de lo que está fuera de soporte o tiene vulnerabilidades conocidas.
• Cobertura de pruebas donde importa. El porcentaje general es menos útil que saber si los caminos del dinero tienen al menos alguna prueba.

Escribe los hallazgos en un documento corto con un costo aproximado para cada punto, como “frena cada release”, “arriesga una caída” o “bloquea una funcionalidad”. Las estimaciones están bien siempre que se indique que lo son. Una revisión más profunda es una auditoría de código aparte. Yo la tomaría como siguiente paso si estas señales se ven mal.

¿Cómo priorizar qué deuda pagar primero?

Piensa en términos de intereses y capital. Los intereses son lo que la deuda te cuesta cada semana. El capital es el esfuerzo para eliminarla. Empieza por los intereses altos con un capital de bajo a moderado.

1. Riesgos de seguridad y de pérdida de datos. Secretos expuestos, falta de control de acceso, ausencia de backups. Esto va primero sin importar el esfuerzo.
2. Caminos del dinero. Todo lo que toque pagos, registro o el flujo que genera ingresos. Un bug aquí tiene un precio directo. Como trabajé en el equipo de carrito y checkout de Total Wine & More, siempre reviso el código de checkout con especial cuidado.
3. Pipeline de entrega. Si los despliegues son manuales y dan miedo, cualquier otra corrección es más lenta y más riesgosa. Arreglar esto temprano baja el costo de todo lo que viene después. Liberar mediante un despliegue canario, primero para unos pocos usuarios, hace que los despliegues den mucho menos miedo.
4. Puntos calientes. Archivos que cambian seguido y se rompen seguido.
5. El resto. Déjalo hasta que tengas una razón para tocarlo.

Una regla práctica que uso, y es una heurística mía, no un estándar: paga la deuda en el área donde estás por construir una funcionalidad. Obtienes el beneficio de inmediato, el alcance sigue siendo pequeño y el negocio ve la relación entre la limpieza y la entrega. Reservar una porción fija de cada sprint suele funcionar mejor que una única limpieza heroica. La gran limpieza normalmente se cancela en cuanto aparece una fecha límite.

En Inovaula construí la v2 de una plataforma web y luego lideré al equipo, y llegamos al flujo de entrega más estable que ese equipo había tenido. Mi conclusión personal de esa etapa, no un resultado medido, es que la limpieza funciona mejor como una parte normal del trabajo. No necesita ser un proyecto aparte que requiera permiso.

¿Cuándo es la deuda técnica una razón para modernizar en lugar de parchar?

Parchar funciona cuando la deuda es local: un módulo desordenado, una librería antigua, una suite de pruebas que falta. Vale la pena considerar la modernización cuando la deuda está en los cimientos y cada funcionalidad tiene que pelear contra ella.

Señales de que cruzaste esa línea:

• El framework o el runtime no tiene soporte y no se puede actualizar paso a paso.
• Contratar es difícil porque pocos ingenieros conocen el stack.
• Cada corrección crea un bug nuevo en otro lugar porque las piezas están muy enredadas.
• La arquitectura no soporta algo que el negocio necesita, como múltiples clientes, funcionalidades en tiempo real o escala.
• El costo de parchar, sumado a lo largo de un año, supera el costo de migrar.

Aun así, prefiero una migración incremental a una reescritura big-bang. Una reescritura suele costar más y tardar más, porque el sistema viejo tiene que seguir funcionando en paralelo mientras el nuevo lo alcanza. En avanzzada lideré la migración completa de una plataforma que postula automáticamente a ofertas de empleo en nombre de sus usuarios. Migramos toda su arquitectura de un stack legado a uno nuevo mientras la gente la seguía usando todos los días. La regla que sigo para este tipo de migración es poner un interruptor delante de todo antes de escribir código nuevo. Luego mueves una pieza a la vez.

Parcha lo pequeño, moderniza los cimientos y no confundas una cosa con la otra.

¿Quieres una segunda opinión sobre tu base de código?

Si heredaste una base de código y no sabes qué deuda importa, escribe a me@filipeeduardo.dev. Incluye una descripción breve del stack y de lo que duele, y te diré qué revisaría primero.