# Qué es la deuda técnica en programación y cómo gestionarla URL: https://whatshouldibuildnext.com/es/journal/que-es-la-deuda-tecnica-programacion Type: blog Locale: es Published: 2026-09-12 Updated: 2026-09-13 --- > La deuda técnica es el coste acumulado de cada atajo para publicar más rápido. Esta guía práctica explica los tipos que importan y cómo gestionarla siendo builder en solitario. ## Qué es la deuda técnica en programación y por qué tu proyecto ya acumula más de lo que crees Que es la deuda tecnica programacion: el coste acumulado de cada atajo que tomaste para publicar más rápido. El término lo acuñó Ward Cunningham en 1992 como metáfora de la deuda financiera, pides prestado ahora y pagas intereses después. Lo que la diferencia del código malo ordinario es la intención: un compromiso, consciente o no, entre velocidad a corto plazo y mantenibilidad a largo plazo. Si alguna vez dejaste un comentario TODO en un fichero, hardcodeaste un valor porque necesitabas publicar antes del viernes, o copiaste y pegaste una función en lugar de extraer un módulo compartido, has acumulado deuda técnica. La mayoría de los side projects están construidos sobre ella, y la mayoría de los devs en solitario cargan con más de lo que creen. ## Por qué los builders en solitario acumulan deuda más rápido que los equipos Los equipos tienen fricción integrada. Code review, discusiones de arquitectura, documentos de estándares: todo esto ralentiza el trabajo, pero también frena la acumulación de deuda. Como dev en solitario, no tienes esa fricción. Tú tomas cada decisión solo, en tiempo real, a las 23h cuando solo quieres ver si la cosa funciona. El resultado es una base de código que refleja cada compromiso que hiciste bajo presión de tiempo. No es un defecto de carácter. Es la realidad estructural de construir en solitario. El problema es que la deuda se compone. Una API key hardcodeada es una hora de trabajo para arreglarla. Cuando tienes veinte repartidas por seis ficheros porque el patrón se propagó, es un día entero de arqueología antes de poder empezar a arreglar nada. Hay también una forma más sutil de acumulación: la deuda arquitectónica generada por decisiones tomadas cuando el proyecto era pequeño y que no aguantan cuando el proyecto consigue tracción. Un fichero JSON plano como base de datos funciona bien a cero usuarios. Es un problema a quinientos. Los devs que conozco que llevan side projects en paralelo con su trabajo diario se enfrentan a esto constantemente: optimizan para velocidad de publicación, absorben la deuda, la renegocian después, si es que hay un después. ## Los cuatro tipos de deuda técnica que importan de verdad No toda deuda es igual. Aquí tienes un desglose práctico para side projects en concreto. **La deuda de código** es la más común. Cubre los atajos en el propio código: lógica duplicada, funciones que hacen demasiadas cosas, variables llamadas `temp2` que siguen ahí seis meses después. Esta es la deuda que sientes cada vez que añades una funcionalidad y pasas treinta minutos solo intentando entender qué hace el código existente antes de poder cambiarlo. **La deuda de documentación** está subestimada por los builders en solitario porque no hay nadie más a quien confundir. Luego te tomas tres semanas de descanso del proyecto, vuelves, y pasas cuatro horas intentando entender por qué construiste la API de esa manera en particular. Estás confundido por tus propias decisiones de hace dos meses. Asumir que recordarás el contexto casi siempre es un error. **La deuda de seguridad** se acumula cuando omites la validación de entradas, dejas rutas de administración desprotegidas durante el desarrollo y te olvidas de bloquearlas, o sigues usando una librería que tiene una vulnerabilidad crítica parcheada hace seis versiones. En un side project esto suele parecer de bajo riesgo hasta que consigues usuarios reales. Entonces ya no es teórico. **La deuda de tooling** es de la que los builders hablan menos. Sin pipeline de despliegue. Pasos manuales para publicar. Un fichero `.env` que solo existe en tu portátil sin formato documentado. Cuando algo falla en producción, esta es la deuda que convierte una solución de treinta minutos en una recuperación de tres horas en la que también tienes que reconstruir el contexto de cómo se despliega todo. ![Cuatro categorías de deuda técnica ilustradas con notas adhesivas de colores en un espacio de trabajo de desarrollador](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/whatshouldibuildnext/2026-09/3191ee-inline1.webp) ## Cuándo asumir deuda técnica es la decisión correcta Esto es lo que la literatura de software empresarial no acierta: tratar la deuda como algo uniformemente malo. Para un builder en solitario o un indie hacker, algo de deuda es la decisión correcta. Tienes un side project que quieres validar en dos semanas. Escribir una suite de tests completa antes de saber si la cosa tiene algún usuario no es disciplina de ingeniería. Es procrastinación con buen nombre. Omitir los tests a cero usuarios y añadirlos una vez que tienes diez clientes de pago es un compromiso deliberado y razonable. El propio Ward Cunningham llamó a esto deuda "prudente y deliberada": sabes que la estás asumiendo, entiendes las consecuencias y planeas devolverla. El problema es cuando los builders asumen deuda sin darse cuenta, o la asumen de forma deliberada y nunca planifican el pago. Deuda sin plan es simplemente entropía. La regla que funciona en la práctica: la deuda está bien cuando está acotada. Un valor de configuración hardcodeado es manejable. El mismo patrón aplicado en treinta ficheros distintos es una base de código en la que nadie puede trabajar, incluido tú. Esto es lo que falla en la práctica: la mayoría de los builders en solitario no rastrean su deuda. Existe como una incomodidad vaga en el fondo de la cabeza. Ese es el problema real, no la deuda en sí, sino la falta de visibilidad sobre qué es exactamente y cuánto costará arreglarla. ## Cómo ver tu deuda antes de que empiece a costar caro La forma más barata de gestionar la deuda es hacerla visible. Eso no requiere un proceso complejo. Un simple fichero `DEUDA.md` en la raíz de tu repositorio donde anotes los compromisos a medida que los tomas lleva treinta segundos por entrada y ahorra horas de redescubrimiento después. Una entrada típica podría tener este aspecto: `## [2026-08-03] Cadena de conexión DB hardcodeada en api/users.ts Por qué: Necesitaba publicar la demo antes del viernes. Coste: Específico al entorno, falla si alguien más intenta ejecutarlo en local. Solución: Mover a variable de entorno con dotenv. Estimado 20 min. Prioridad: Alta, antes de que se una cualquier colaborador.`Ya está. El formato no importa. El acto de escribirlo importa porque te obliga a articular el compromiso de forma explícita en lugar de dejarlo evaporarse en el código donde acumulará intereses en silencio. Las herramientas de análisis estático hacen una versión diferente de esto de forma automática. Herramientas como SonarQube o CodeClimate escanean tu base de código y marcan code smells, duplicaciones, puntos de seguridad y puntuaciones de complejidad. Son más útiles para detectar deuda que no sabías que estabas creando: el tipo inadvertido que aparece cuando no te das cuenta de que estás aplicando el mismo patrón doce veces seguidas. CodeScene va un paso más allá al analizar el historial de commits para identificar qué ficheros cambian juntos y qué puntos calientes se tocan repetidamente bajo presión de tiempo. Para un proyecto en solitario, este tipo de señal es más accionable que un snapshot estático: te muestra dónde has estado haciendo compromisos repetidamente, no solo dónde el código tiene mal aspecto ahora mismo. ## Tres formas de pagar la deuda sin parar el trabajo El error es tratar el pago de deuda como un sprint dedicado que programas para el mes que viene y al que nunca llegas. El enfoque correcto es pagarla de forma continua en pequeñas cantidades, integradas en tu flujo normal. **La Regla del Boy Scout aplicada al código**: deja el fichero que editas ligeramente mejor de como lo encontraste. Renombra la variable confusa mientras ya estás ahí. Extrae la lógica duplicada en una función mientras la tocas de todas formas. Esto cuesta entre cinco y quince minutos por sesión y se capitaliza significativamente a lo largo de meses de trabajo constante. **Presupuesto de deuda durante el desarrollo activo**: si estás construyendo una nueva funcionalidad, asigna el 20% del tiempo a arreglar deuda en el código adyacente. No la deuda que descubres en una parte distante de la base de código: esa puede esperar. La deuda que toca directamente lo que estás construyendo ahora mismo. Esto evita el patrón habitual en el que las nuevas funcionalidades empeoran la deuda antigua porque se construyen sobre ella. **Triaje de prioridades por radio de impacto**: no toda la deuda merece la misma atención. La deuda en código que tocas cada semana importa más que la deuda en un módulo que no has abierto en cuatro meses. A la hora de decidir qué abordar, pregúntate: si esto falla o necesita cambiar, cuántas otras cosas afecta. Radio de impacto alto, prioridad alta. La deuda de radio de impacto bajo que vive en un rincón que visitas raramente puede quedarse ahí. Una regla tres a uno funciona para el desarrollo activo: por cada tres sesiones construyendo nuevas funcionalidades, dedica una sesión a pagar deuda. Esto mantiene la proporción bajo control sin detener el progreso. ![Developer revisando y refactorizando código en una oficina en casa tranquila](https://fdzlnqpwsaniezitwiuw.supabase.co/storage/v1/object/public/cms-media/whatshouldibuildnext/2026-09/b8ca4d-inline2.webp) ## Lo que tu carga de deuda actual te está diciendo A los seis meses de un proyecto, la distribución de deuda en tu base de código es un mapa bastante preciso de las decisiones tomadas bajo presión. Mucha deuda en el módulo de autenticación significa que ibas con prisa cuando lo construiste. Duplicación masiva en tu capa de API significa que estabas validando funcionalidades rápidamente y no te detuviste a consolidar. Complejidad densa en un fichero concreto suele significar que ese fichero se convirtió en un vertedero cuando la arquitectura no estaba clara. Esta información es genuinamente útil. Te muestra qué partes de tu base de código se construyeron con confianza y cuáles se construyeron con incertidumbre. Las partes construidas con incertidumbre son también a menudo las partes que resultaron no importar: funcionalidades que validaste rápidamente y luego desapriorizaste. La deuda que acumulaste ahí puede que nunca necesite pagarse porque esos caminos no llevan a ningún lado. Las partes que sí resultaron importar: flujos principales de usuario, modelo de datos, contratos de API, autenticación. Esas son donde pagar la deuda realmente vale la pena. No estás intentando escribir código perfecto en todas partes. Estás intentando identificar las paredes de carga y mantenerlas limpias. Si tu base de código ha llegado al punto en que añadir cualquier funcionalidad lleva más tiempo depurando el comportamiento existente que escribiendo código nuevo, esa es la señal. No una señal para parar y reescribir todo: eso casi nunca es la decisión correcta, y se estima que lleva el doble de tiempo de lo que crees. Es una señal para dedicar las próximas tres o cuatro semanas a la reducción de deuda específica en los módulos concretos que están causando el freno. ## Reescribir o refactorizar las partes desordenadas Esta es la pregunta que enfrentan los builders en solitario cuando la deuda empieza a sentirse inmanejable. La respuesta casi siempre es refactorizar, no reescribir. Las reescrituras se estiman que llevarán la mitad del tiempo que realmente tardan. También pierden el conocimiento acumulado en el código existente: los casos extremos manejados, los bugs arreglados, las soluciones temporales para las peculiaridades de APIs de terceros que descubriste a las malas. Pagas la deuda original dos veces: una vez cuando la cargaste, y otra cuando tienes que redescubrir todo mientras reconstruyes. La refactorización funciona cuando está bien enfocada. Elige el módulo que causa el dolor más concreto: el más lento de cambiar, donde se originan más bugs, el más difícil de entender. Obtén una imagen completa de qué hace antes de cambiar nada. Añade tests alrededor de los límites para poder refactorizar con seguridad sin romper el comportamiento adyacente. Haz los cambios de forma incremental a lo largo de varias sesiones, no en un único sprint heroico que deja las cosas a medias si te quedas sin energía. Tres razones para refactorizar, una razón para no hacerlo: refactoriza cuando la deuda está en una zona de alto tráfico de la base de código, cuando estás a punto de construir sobre ella, o cuando está causando bugs reales. Omite la refactorización cuando el módulo es estable, cambia raramente y la deuda está autocontenida. No es una idea perfecta. Es una idea viable: la versión sostenible de la gestión de deuda técnica no es cero deuda. Es deuda que entiendes, puedes articular, y estás decidiendo activamente cargar o pagar. Esa claridad es el objetivo real. ## FAQ ### ¿Qué es la deuda técnica en programación exactamente? La deuda técnica es el coste acumulado de los atajos que tomas para publicar más rápido. El término lo acuñó Ward Cunningham en 1992 como metáfora de la deuda financiera: pides prestado tiempo ahora y pagas intereses después en forma de código más difícil de mantener y extender. ### ¿Cuáles son los tipos de deuda técnica más comunes? Los cuatro tipos que más impactan a los proyectos son: deuda de código (lógica duplicada, funciones complejas), deuda de documentación (contexto perdido), deuda de seguridad (validaciones omitidas, librerías desactualizadas) y deuda de tooling (falta de pipeline de despliegue, pasos manuales). ### ¿Cuándo es correcto asumir deuda técnica? Cuando es deliberada y acotada. Omitir los tests durante la fase de validación de un side project a cero usuarios es una decisión razonable. El problema aparece cuando la deuda se asume sin conciencia o sin plan de pago. Deuda sin plan es entropía. ### ¿Cómo puedo hacer visible mi deuda técnica? La forma más simple es un fichero DEUDA.md en la raíz del repositorio donde anotes cada atajo con su fecha, coste estimado y plan de solución. Las herramientas de análisis estático como SonarQube y CodeClimate automatizan esta detección para la deuda inadvertida. ### ¿Es mejor refactorizar o reescribir cuando la deuda es alta? Casi siempre es mejor refactorizar. Las reescrituras llevan el doble del tiempo estimado y pierden el conocimiento acumulado en el código existente: los casos extremos manejados, los bugs arreglados, las soluciones para APIs de terceros. Refactoriza de forma incremental, módulo a módulo. ### ¿Cuánto tiempo debo dedicar a pagar deuda técnica? Una regla práctica para desarrollo activo: por cada tres sesiones construyendo nuevas funcionalidades, dedica una sesión a pagar deuda. Además, asigna el 20% del tiempo de cada nueva funcionalidad a arreglar la deuda adyacente al código que estás tocando. ### ¿Qué herramientas ayudan a gestionar la deuda técnica en proyectos pequeños? SonarQube detecta code smells y puntos de seguridad. CodeClimate rastrea la mantenibilidad a lo largo del tiempo. CodeScene analiza el historial de commits para identificar qué ficheros se tocan repetidamente bajo presión, que es la señal más útil para un proyecto en solitario.