Tracking Deuda Técnica | Guía GitScrum

Rastrea y gestiona deuda técnica sistemáticamente con labels dedicados, workflows de priorización y asignación de sprint.

9 min de lectura

La deuda técnica se acumula silenciosamente hasta que paraliza la velocidad de desarrollo. GitScrum proporciona tracking estructurado con labels, priorización y asignación de sprint para gestionar deuda sistemáticamente antes de que se convierta en emergencia.

El Problema de la Deuda Técnica

Deuda sin rastrear crea problemas compuestos:

• Acumulación invisible — Sin visibilidad del crecimiento de deuda
• Diferida indefinidamente — Siempre desprioritizada por features
• Crisis repentinas — Pequeños problemas se vuelven grandes outages
• Decline de velocidad — Todo toma más tiempo con el tiempo
• Frustración de desarrolladores — Trabajar en codebases degradadas
• Errores de estimación — La deuda hace impredecible el nuevo trabajo

Solución de Tracking de Deuda GitScrum

Gestión sistemática de deuda en GitScrum:

Características Clave

Configurando Tracking de Deuda

Crear Labels de Deuda

Labels para Deuda Técnica:
├── tech-debt          (categoría padre)
├── debt-architecture  (problemas estructurales)
├── debt-performance   (velocidad/eficiencia)
├── debt-security      (preocupaciones de seguridad)
├── debt-testing       (gaps de cobertura de tests)
├── debt-documentation (docs faltantes)
└── debt-dependencies  (paquetes desactualizados)

Niveles de Prioridad

Matriz de Prioridad para Deuda:
├── Crítica — Bloqueando features o causando incidentes
├── Alta    — Ralentizando significativamente desarrollo
├── Media   — Fricción notable, manejable
└── Baja    — Limpieza, nice to have

Crear Template de Deuda

Template de Tarea: Item de Deuda Técnica

Título: [DEBT] Descripción breve
Descripción:
  - Qué: Estado problemático actual
  - Por qué: Cómo esto se volvió deuda
  - Impacto: Efecto en desarrollo/producto
  - Solución: Enfoque de fix propuesto
  - Esfuerzo: Tiempo estimado para resolver
  - Riesgo: Consecuencias si no se aborda

Labels: tech-debt, [tipo-de-deuda]
Prioridad: [Crítica/Alta/Media/Baja]

Capturando Deuda Técnica

Cuándo Registrar Deuda

Registrar deuda cuando:
├── Implementando workarounds para enviar features
├── Saltando tests para cumplir deadlines
├── Copiar-pegar en vez de refactorizar
├── Ignorando advertencias de deprecación
├── Hardcodeando valores que deberían ser config
├── Dejando comentarios TODO en código
└── Descubriendo conocimiento tribal no documentado

Ejemplo de Tarea de Deuda

[DEBT] Módulo de pagos usa API de Stripe deprecada

Qué: Procesamiento de pagos usa Stripe API v1, deprecada 
desde 2023. El código actual aún funciona pero no recibe 
actualizaciones de seguridad.

Por qué: Implementación original en 2021, sin capacidad 
para migración durante pushes de features.

Impacto: 
- Riesgo de seguridad por API sin mantenimiento
- Faltan nuevas features de pago
- Fallará cuando v1 sunset (Ene 2025)

Solución: Migrar a Stripe API v3
- Actualizar dependencia del SDK
- Refactorizar servicio de pagos
- Actualizar handlers de webhook
- Testear todos los flujos de pago

Esfuerzo: 3-5 días para desarrollador senior
Riesgo: Alto - servicio fallará después de fecha de sunset

Labels: tech-debt, debt-security, debt-dependencies
Prioridad: Crítica
Deadline: Antes de Ene 2025

Priorización de Deuda

Matriz Impacto/Esfuerzo

                    Bajo Esfuerzo   Alto Esfuerzo
                   ┌───────────────┬───────────────┐
Alto Impacto       │ HACER PRIMERO │ PLANIFICAR    │
                   │ Quick wins    │ Trabajo mayor │
                   ├───────────────┼───────────────┤
Bajo Impacto       │ LLENAR GAPS   │ DIFERIR       │
                   │ Limpieza fácil│ No vale la    │
                   └───────────────┴───────────────┘

Criterios de Priorización

Asignación de Sprint para Deuda

La Regla del 20%

Capacidad del Sprint: 100 puntos
├── Features: 80 puntos (80%)
└── Tech Debt: 20 puntos (20%)

Asignación consistente previene:
- Acumulación de deuda
- Varianza sprint-a-sprint
- "Sprints de deuda" que frustran stakeholders

Planificación de Sprint de Deuda

Planificación de Sprint para Deuda:

1. Revisar backlog de deuda
2. Verificar items críticos/alta prioridad
3. Matchear a capacidad disponible (20%)
4. Seleccionar items que:
   - Emparejan bien con features planeadas
   - Abordan pain points actuales
   - Tienen criterios de completitud claros
5. Asignar a desarrolladores con contexto

Vinculando Deuda a Features

Conectar Trabajo Relacionado

Tarea de Feature #234: Agregar facturación de suscripción
├── Tareas de Deuda Vinculadas:
│   ├── #198: [DEBT] Migrar a Stripe API v3
│   │   └── Razón: Requerido para features de suscripción
│   ├── #210: [DEBT] Agregar lógica de retry de pagos
│   │   └── Razón: Suscripciones necesitan auto-retry
│   └── #215: [DEBT] Mejorar manejo de errores de pago
│       └── Razón: Mejor UX para fallos recurrentes

Beneficios de Vincular

• Justificar trabajo de deuda a stakeholders
• Surfacear prerrequisitos ocultos
• Estimaciones de features precisas
• Resolución natural de deuda durante features

Visibilidad de Deuda

Vista de Board para Deuda

Kanban Board: Deuda Técnica
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ Backlog (23) │ Planeado (5) │ En Progreso  │ Resuelto (8) │
├──────────────┼──────────────┼──────────────┼──────────────┤
│ [DEBT] Auth  │ [DEBT] API   │ [DEBT] Stripe│ [DEBT] Tests │
│ [DEBT] Cache │ [DEBT] Logs  │ migración    │ [DEBT] Docs  │
│ [DEBT] Tests │ [DEBT] DB    │              │ ...          │
│ ...          │ ...          │              │              │
└──────────────┴──────────────┴──────────────┴──────────────┘

Métricas de Dashboard

Dashboard de Deuda Técnica
━━━━━━━━━━━━━━━━━━━━━━━━━━

Total Items de Deuda: 45
├── Crítica: 3 🔴
├── Alta: 12 🟡
├── Media: 18 🟢
└── Baja: 12 ⚪

Este Sprint:
├── Planeados: 5 items (23 puntos)
└── Resueltos: 3 items (15 puntos)

Tendencia: ↓ 4% del mes pasado
Item Más Antiguo: 8 meses (migración DB)

Documentación en NoteVault

Registro de Deuda Técnica

NoteVault: Registro de Deuda Técnica

## Visión General
Este documento rastrea items mayores de deuda técnica 
y su contexto de negocio.

## Deuda Activa

### Sistema de Pagos
- **Problema**: API de Stripe v1 deprecada
- **Dueño**: @backend-team
- **Estado**: Planeado para Q1
- **Impacto de Negocio**: Riesgo seguridad, features faltantes
- **Plan de Resolución**: #198

### Autenticación
- **Problema**: Sin rotación de refresh token
- **Dueño**: @security-team
- **Estado**: En progreso
- **Impacto de Negocio**: Gap de compliance de seguridad
- **Plan de Resolución**: #245

## Deuda Resuelta
| Item | Resuelto | Tiempo Gastado | Notas |
|------|----------|----------------|-------|
| Legacy ORM | Nov 2024 | 2 semanas | Migración completa |
| Cobertura tests | Oct 2024 | 3 sprints | 40% → 80% |

Revisiones de Deuda

Reuniones Regulares de Deuda

Revisión Mensual de Deuda Técnica

Agenda:
1. Revisar métricas de deuda (15 min)
   - Nueva deuda registrada
   - Deuda resuelta
   - Dirección de tendencia

2. Triaje de nuevos items (20 min)
   - Asignar prioridad
   - Estimar esfuerzo
   - Identificar quick wins

3. Planificar próximo sprint (15 min)
   - Seleccionar deuda para próximo sprint
   - Asignar dueños
   - Vincular a features

4. Discutir bloqueadores (10 min)
   - Items bloqueados
   - Necesidades de recursos
   - Alineación con stakeholders

Integración en Retrospectiva

Retrospectiva del Sprint

¿Qué nos ralentizó?
├── "Fallos de retry de pago desperdiciaron 2 días debugging"
│   └── Acción: Priorizar #210 (deuda de lógica de retry)
├── "Tests flaky causaron falsas alarmas"
│   └── Acción: Agregar #260 (deuda de estabilidad de tests)

Previniendo Nueva Deuda

Definición de Hecho

Definición de Hecho (incluye prevención de deuda):
☑ Feature completa según requisitos
☑ Tests unitarios escritos (>80% cobertura)
☑ Tests de integración pasan
☑ Documentación actualizada
☑ Sin nuevos comentarios TODO sin ticket
☑ Dependencias actualizadas si se tocaron
☑ Code review aprobado
☑ Sin advertencias de seguridad
☑ Performance aceptable

Checklist de Code Review

Code Review Consciente de Deuda:

□ ¿Esto introduce nueva deuda?
  - Si sí, ¿ticket creado?
□ ¿Esto resuelve alguna deuda existente?
  - Si sí, vincular y cerrar ticket de deuda
□ ¿Hay workarounds?
  - Documentar por qué, crear ticket de limpieza
□ ¿Las dependencias están actualizadas?
  - Verificar deprecaciones
□ ¿Se mantiene la cobertura de tests?
  - Sin regresión de cobertura

Comunicando Deuda a Stakeholders

Traducción a Lenguaje de Negocio

Técnico → Impacto de Negocio

"API está deprecada"
→ "Riesgo de seguridad: sin parches después de enero"

"Cobertura de tests es baja"  
→ "Riesgo de release: bugs más probables en producción"

"Arquitectura es monolítica"
→ "Velocidad de entrega: features toman 3x más tiempo"

"Dependencias están desactualizadas"
→ "Riesgo de compliance: vulnerabilidades conocidas"

Reporte de Burn-down de Deuda

Reporte de Deuda Técnica Q4

Inicio Q4: 52 items de deuda (312 puntos)
Resueltos: 18 items (98 puntos)
Agregados: 7 items (43 puntos)
Fin Q4: 41 items (257 puntos)

Reducción Neta: 11 items (55 puntos) ↓17%

Highlights:
✓ Completada migración Stripe (crítica)
✓ Cobertura de tests mejoró 15%
⚠ Migración de base de datos aún pendiente

Soluciones Relacionadas

• Gestionar código legacy en proyectos activos
• Métricas de calidad de código y tracking
• Planificación de sprint con trabajo técnico