Documentación de Deuda Técnica | GitScrum
Documenta deuda técnica sistemáticamente para tomar decisiones informadas sobre cuándo y cómo abordarla.
3 min de lectura
La deuda técnica se acumula silenciosamente, frenando el desarrollo hasta que los equipos no pueden ignorarla. La documentación hace la deuda visible, cuantificable, y accionable. Deuda bien documentada permite trade-offs informados entre pagarla y entregar features.
Elementos de Documentación
| Elemento | Propósito | Ejemplo |
|---|---|---|
| Descripción | Qué es la deuda | Sistema de auth legacy |
| Ubicación | Dónde vive | /src/auth/*.js |
| Impacto | Cómo daña | +2h por feature |
| Costo | Esfuerzo para arreglar | 3 sprints |
| Riesgo | Qué podría pasar | Breach de seguridad |
Formato de Documentación de Deuda
TEMPLATE DE ITEM DE DEUDA TÉCNICA
═════════════════════════════════
TÍTULO:
─────────────────────────────────────
Nombre claro, conciso
"Sistema de autenticación legacy"
"Suite de tests monolítica"
"Respuestas de API inconsistentes"
DESCRIPCIÓN:
─────────────────────────────────────
¿Qué es la deuda?
¿Por qué existe?
¿Cuándo se introdujo?
Ejemplo:
"Autenticación fue construida rápido para MVP.
Usa versión outdated de bcrypt, sin OAuth,
gestión de sesión es custom-built.
Introducido: 2021 Q2, hace 3 developers."
UBICACIÓN:
─────────────────────────────────────
¿Qué archivos/servicios/módulos?
├── /src/auth/
├── /src/middleware/session.js
├── /src/controllers/login.js
├── Relacionado: /tests/auth/*.test.js
└── Líneas afectadas: ~2000
IMPACTO:
─────────────────────────────────────
¿Cómo nos frena?
├── Features nuevas de auth toman +2 días
├── Onboarding: 1 semana para entender
├── Reviews de seguridad lo marcan siempre
├── CI corre 15 min más
└── Cuantificar donde sea posible
COSTO PARA ARREGLAR:
─────────────────────────────────────
¿Qué tomaría remediación?
├── Esfuerzo estimado: 3 sprints
├── Skills necesarios: Backend senior
├── Dependencias: Ninguna
└── Riesgo: Medio (sistema core)
RIESGO SI SE IGNORA:
─────────────────────────────────────
¿Qué pasa si no lo arreglamos?
├── Vulnerabilidades de seguridad
├── Velocidad de desarrollo sigue bajando
├── Onboarding toma más tiempo
└── Eventualmente se vuelve blocker
En GitScrum
DEUDA TÉCNICA EN GITSCRUM
═════════════════════════
TRACKING:
┌─────────────────────────────────────────────────────────────┐
│ │
│ • Label "tech-debt" en tareas │
│ • Backlog separado o integrado │
│ • Campos custom para impacto/costo │
│ • Reportes de deuda │
│ │
└─────────────────────────────────────────────────────────────┘