Se admite deuda técnica

Un día los arquitectos dicen "se admite deuda técnica" y quien escucha a conciencia ya sabe lo que se viene. Qué cuenta como deuda y qué no, el cuadrante de Fowler, cómo una deuda sana se muda de cuadrante sola, y una estructura mínima para registrarla en dos minutos.

Un día, en una reunión, los arquitectos dicen: "se admite deuda técnica".

El que escucha eso a conciencia se pega una palmada en la frente, porque ya sabe lo que se viene.

#El que sale corriendo detrás de la pelota

Algunos salen corriendo detrás de la pelota. Bajo criterio, sin cuestionar nada, a hacer por hacer.

Empezás a ver problemas de naming. Arquitectura que cambia según el mindset y el humor de quien programó ese día. Intenciones acopladas donde no debería haber ninguna relación. Tablas y entidades Dios que hacen de todo un poco. Una distinción de responsabilidades tan anémica que ya ni se nota. Todos corriendo, porque "no hay tiempo".

#El día que nadie se hace cargo

Llega el día. Y nadie se hace cargo de nada.

Nadie registró la deuda técnica. Buena parte quedó sepultada en el código, y ya nadie recuerda por dónde agarrar el hilo para empezar a pagarla. Cambian las cabezas del equipo, y lo único que queda es la frase de siempre: "esto anda de milagro".

#"Anda de milagro" es un insulto

Decir que algo "anda de milagro" suena inofensivo. No lo es.

Si algo anda, no es milagro — es que en algún momento alguien pensó el criterio de diseño con el que funciona. Las cosas funcionan según para qué fueron pensadas. Llamarlo "milagro" borra ese trabajo, y de paso desmerece al desarrollador que sí se tomó el tiempo de pensarlo, mientras premia con la misma etiqueta a quien no pensó nada y tuvo suerte.

#No hay deuda buena o mala — hay intención

Antes de seguir conviene fijar de qué estamos hablando, porque "deuda técnica" se usa para todo.

Deuda técnica es toda decisión tomada para ir más rápido hoy que genera un costo extra —en tiempo, riesgo o esfuerzo— para modificar el sistema mañana. La clave no es "código feo": es el trade-off entre velocidad y calidad estructural, lo tomes a conciencia o no.

Entonces la pregunta no es si la deuda técnica es aceptable en abstracto. Es si la tomaste con intención, con contexto, respondiendo a una necesidad de negocio real — o si simplemente apareció porque nadie tuvo tiempo de pensar.

Martin Fowler ordenó esto en dos ejes, y es el marco que más me sirve:

El único cuadrante que se elige es prudente + deliberada: sabés qué estás dejando atrás y sabés que lo vas a pagar. Prudente + inadvertida no se elige, se aprende — el diseño correcto aparece recién después de haberlo hecho, y ahí lo único que corresponde es registrarlo.

Los dos imprudentes son los que se vuelven trampa. Y el peor no es el deliberado, es el de abajo a la derecha: si nadie decidió nada, no hay nada que registrar ni nadie que después recuerde por qué.

#Del provisorio al provisiempre

Hay algo que el cuadrante, dibujado así, no muestra: no es una foto. Es dónde estaba parada la deuda en el momento en que la tomaste, y esa posición se mueve.

Una deuda prudente y deliberada se convierte en imprudente y deliberada en un momento muy preciso: cuando el equipo ya sabe que existe y, sabiéndolo, sigue construyendo encima sin ponerle fecha. Ahí deja de ser "shippeamos ahora y lo arreglamos después" y pasa a ser "no tenemos tiempo de hacerlo bien" — que es, textual, el cuadrante imprudente.

Lo que empuja esa mudanza es que cada cosa nueva que apoyás encima sube el precio de pagarla. La decisión provisoria se vuelve estructural: primero la usa un módulo, después tres, después el diseño entero asume que las cosas son así. El provisorio se transformó en provisiempre, y ya no estás pagando un atajo — estás rehaciendo el sistema.

Por eso el registro no es burocracia. Una deuda prudente sin fecha y sin dueño no se queda quieta esperando que la pagues: se muda de cuadrante sola.

#Qué entra y qué no

Buena parte de las discusiones sobre deuda técnica son, en realidad, discusiones sobre qué cuenta como deuda. Esto es lo que uso para cortarlas.

Sí es deuda:

• Código duplicado que deberías haber abstraído.
• Falta de tests en lógica crítica.
• Arquitectura que no soporta un caso de uso que ya sabés que viene — un monolito cuando ya sabés que vas a tener que escalar un módulo aparte.
• Librerías o frameworks desactualizados que bloquean upgrades futuros.
• Documentación inexistente, que convierte cada cambio en un trabajo de arqueología.
• Decisiones de diseño tomadas para salir del paso — lógica de negocio en el controller en lugar del dominio.
• Dependencias mal desacopladas: esa violación de hexagonal que dejaste pasar.

No es deuda, aunque se le diga así:

• Bugs. Un bug es un defecto, no una decisión. La deuda es sobre diseño, no sobre errores funcionales.
• Features que faltan. Eso es backlog de producto.
• Código viejo que anda bien y no bloquea nada. Si no te está costando nada modificarlo, no es deuda — es código viejo, y está perfecto que exista.
• "No me gusta cómo está escrito esto". El gusto no es deuda si no genera fricción real y medible.

Y cuando dudes, el test rápido: ¿esto me está costando tiempo o riesgo ahora, cada vez que toco código cerca? ¿O es una preocupación teórica?

Si es teórica, no es deuda: es una opinión de arquitectura. Puede ser muy buena opinión, pero se prioriza distinto — mucho más abajo en la lista.

#El atajo cognitivo: fusionar lo que no debería fusionarse

Bajo presión, el atajo casi nunca es "salteemos el test". Es más sutil: reutilizar y fusionar cosas que tienen intenciones distintas y casos de uso distintos, porque a corto plazo se siente como avanzar más rápido.

// Una sola entidad haciendo de persistencia, contrato de API y evento
public class Order
{
    public Guid Id { get; set; }
    public string CustomerEmail { get; set; }     // necesario para el evento, no para persistir
    public decimal InternalDiscount { get; set; } // no debería salir nunca en la API
    public string Status { get; set; }
}

Order sirve para todo, hasta que un día el evento necesita un campo que la tabla no tiene, o la API expone un campo que nunca debió salir. Cada reuso planta una asunción que se rompe apenas uno de esos tres casos de uso cambia solo.

Y sí: en la sección anterior puse el código duplicado como deuda, y acá estoy diciendo lo contrario. No es contradicción — son la misma falla vista de los dos lados. Duplicar lo que en realidad es una sola cosa y fusionar lo que en realidad son tres es, en ambos casos, no haberse preguntado cuántas intenciones distintas hay en juego.

#La deuda cobra intereses

La deuda técnica no explota de golpe. Es un gasto hormiga: se va acumulando de a poco, nadie lleva registro, y no se siente hasta el día en que hay que tocar el código de al lado.

Alguna vez nos pasó, a mí y al equipo de turno.

Tomamos una deuda en febrero con fecha de pago para después de mayo, que era cuando salía el despliegue productivo. Sonaba razonable: shippeamos ahora y, con el sistema ya en producción, nos queda aire para volver y hacerlo bien.

No quedó documentada, y nadie le hizo seguimiento. El aire que todos asumimos que íbamos a tener nunca apareció, porque nadie midió algo bastante obvio: después del despliegue no viene la calma, vienen los evolutivos.

Lo que corría como voz era "que lo resuelva el equipo de mantenimiento". Nadie midió la otra mitad de esa frase: que el equipo de mantenimiento podíamos llegar a ser nosotros mismos.

Ahí empezó lo que de verdad duele. Cada cambio nuevo se apoyó en la deuda que ya estaba, y construir sobre deuda genera más deuda. La deuda empezó a cobrar intereses.

La única parte feliz de la historia es la línea de gestión, porque la pantallita muestra lo mismo que el Word. Por detrás, cada cambio que no se resuelve de raíz cuesta más caro en tiempo de resolución. Lo que podía tomar un día empieza a estimarse en tres. Después en una semana.

Y cuando las estimaciones se estiran lo suficiente, aparece el comentario:

—¿Y por qué no lo hicimos así desde el principio?

Adiviná quién queda pegado como responsable. Es la misma dinámica sobre la que escribí en Parecen no haberme escuchado cuando se los dije: sin registro, la versión que queda es la del que la cuenta después.

Y acá está la parte que más me quedó grabada. Esa deuda había arrancado bien: tenía fecha. Era prudente y deliberada, el cuadrante sano. Pero la fecha vivía en la cabeza de un par de personas, no en un documento con dueño — y una fecha que no está escrita no es un compromiso, es una intención.

Cuando los intereses se vuelven visibles, ya nadie recuerda que todo esto salió de una decisión para ir rápido. La deuda quedó; la decisión que la originó, no. Y el que termina explicándola es el que la está pagando.

Por eso los ADR importan tanto acá, y por eso importa sobre todo cuándo se escriben. Un ADR no se escribe post mortem, cuando ya hay que explicar por qué el sistema terminó así. Se escribe mientras estás diseñando la solución — que es el único momento en que todavía no hay nada que justificar.

Escrito ahí deja de ser documentación y pasa a ser un aval: la prueba de que el atajo fue una decisión tomada y aprobada, no un descuido de quien lo implementó. Cuando llegue el "¿y por qué no lo hicimos así desde el principio?" y nadie quiera hacerse cargo de haber aprobado lo otro, ese documento es lo único que queda en pie.

#Registralo rápido, no perfecto

El motivo por el que la deuda casi nunca se registra no es "no quise documentarla" — es que documentarla se siente como perder más tiempo del que ya no hay. Por eso el registro tiene que ser rápido, no prolijo.

No hace falta un proceso. Alcanza con algo auditable:

• Una línea en la wiki de DevOps del equipo, en una página dedicada a deuda técnica: qué quedó pendiente, por qué, y dónde vive en el código.
• Un mail corto, con copia a quien corresponda (TL, arquitectos), contando qué deuda se está tomando y por qué. El mismo principio que un ADR: no hace falta convencer a nadie en el momento, alcanza con que quede fecha y destinatarios.
• Un ticket en el backlog, aunque sea de una sola línea, tageado como deuda técnica.

Lo que sí ayuda es tener una estructura fija, para no arrancar de una hoja en blanco cada vez. Esta es la mínima que uso — texto plano a propósito, así entra igual en un notepad, en la wiki, en Notion o en la descripción de un ticket:

# DT-014 — Validación de cupones duplicada en el checkout

Fecha: 2026-08-19
La tomó: (vos) — acordada con: (TL, arquitectura)
Cuadrante: prudente + deliberada

Qué se hizo: la validación quedó duplicada en el controller en vez de moverse al dominio.
Por qué: la ventana de release no daba para tocar los tres módulos que dependen de eso.
Dónde vive: CheckoutController — validación de cupones.
Qué cuesta hoy: cada cambio en las reglas de cupón hay que hacerlo en dos lugares.
Cuándo se paga: sprint posterior al release. Responsable: (nombre).

Se llena en dos minutos, y cada campo está ahí por un motivo que ya apareció en este post:

• Dónde vive es lo que evita que dentro de seis meses nadie sepa por dónde agarrar el hilo.
• Cuándo se paga y responsable son los que sostienen la deuda en el cuadrante prudente. Sin eso, se muda sola.
• Qué cuesta hoy es lo que te deja priorizarla contra el resto del backlog, en vez de discutirla por gusto.
• La tomó / acordada con es la parte que funciona como aval: deja por escrito que fue una decisión, no un descuido.

Y ojo, que no es lo mismo que un ADR. El ADR registra la decisión de diseño; esto registra el atajo que tomaste respecto de esa decisión, y cuándo pensás volver. Un ADR por decisión de arquitectura; un registro de deuda cada vez que cortás camino a sabiendas — que es bastante más seguido.

El formato importa menos que las propiedades que tiene que cumplir: fecha, quién la tomó, un alcance explícito —hasta dónde llega y hasta dónde no— y un lugar que nadie pueda editar en silencio después. Una deuda que solo existe en la memoria del equipo no está registrada: está esperando la próxima rotación para desaparecer.

#Si te toca moderar la discusión

El lugar donde este marco rinde de verdad es la retro o el refinamiento de backlog.

Cuando alguien dice "eso es deuda técnica", pedile dos cosas: en qué cuadrante cae, y qué costo concreto genera hoy. No como examen, sino para que la conversación deje de ser una lista de quejas y pase a ser una lista priorizable.

En mi experiencia esas dos preguntas filtran más de la mitad de lo que se llama "deuda" y en realidad es preferencia estética. Y lo que queda después del filtro es exactamente lo que vale la pena registrar y pagar.

#El equilibrio

La deuda técnica no es mala en sí misma. Es una herramienta — como el apalancamiento financiero — cuando se elige con intención y queda registrada. Es una trampa cuando es la respuesta automática a "no hay tiempo".

La palmada en la frente de quien escucha "se admite deuda técnica" no es por la deuda. Es porque ya sabe que nadie la va a registrar.

#technical-debt #architecture #team-practices #refactoring