Cómo visualizar y reducir sistemáticamente la deuda técnica con Claude Code

“Queremos refactorizar pero nunca tenemos tiempo.” “¿Por dónde empezamos?” La deuda técnica se acumula silenciosamente. Con Claude Code, puedes exponer, priorizar y saldar la deuda sistemáticamente a una fracción del coste habitual.

1. Detectar code smells en todo el código

Empieza con un barrido completo.

claude -p "
Escanea src/ en busca de code smells. Comprueba:

- Funciones de más de 50 líneas
- Anidamiento profundo (4+ niveles)
- Lógica duplicada
- God Classes (responsabilidades sobrecargadas)
- Números mágicos
- Exports no utilizados
- Uso del tipo any
- Comentarios TODO / FIXME

Salida a docs/tech-debt/smells.md como:
| Archivo | Línea | Smell | Severidad(1-5) | Solución sugerida |
"

Un inventario ordenado por severidad se convierte en tu punto de partida.

2. Medir la deuda de dependencias

Las bibliotecas desactualizadas y las vulnerabilidades también son deuda.

claude -p "
Analiza package.json junto con npm audit y npm outdated:

1. Bibliotecas que necesitan actualizaciones mayores
2. Vulnerabilidades conocidas
3. Paquetes sin mantenimiento
4. Duplicados (por ejemplo, moment + date-fns mezclados)

Salida a docs/tech-debt/dependencies.md con versión actual, última versión, breaking changes, prioridad de actualización — en formato tabla.
"

3. Priorizar con ICE Scores

No puedes arreglarlo todo. Clasifica por Impact × Confidence × Ease.

claude -p "
Usando docs/tech-debt/smells.md y dependencies.md, puntúa cada elemento:

- Impact (I): efecto en el negocio/velocidad de desarrollo (1-10)
- Confidence (C): certeza del impacto (1-10)
- Ease (E): esfuerzo para arreglarlo (1-10)

Ordena de forma descendente por Score = I × C × E.
Salida como docs/tech-debt/backlog.md.
Incluye días-persona estimados para los 10 primeros.
"

Las puntuaciones numéricas hacen que el argumento sea claro para los product managers.

4. Generar automáticamente pequeños PRs de pago

Divide el pago en PRs revisables.

claude -p "
Para el elemento nº 1 en docs/tech-debt/backlog.md:

1. Crea la rama: refactor/tech-debt-001
2. Arregla solo ese problema (sin cambio de comportamiento)
3. Verifica que los tests existentes pasan
4. Divide en varios commits si es grande
5. Ejecuta gh pr create

El cuerpo del PR debe incluir:
- En qué consistía la deuda
- Por qué saldarla ahora
- ICE score
- Radio de impacto en otro código
"

5. Identificar hot spots sin tests

Las zonas con baja cobertura se convierten en deuda futura.

npm test -- --coverage --coverageReporters=json

claude -p "
Analiza coverage/coverage-summary.json:

- Archivos con menos del 50 % de cobertura
- De esos, cuáles contienen lógica de negocio
- Prioridad para añadir tests

Salida a docs/tech-debt/coverage-gaps.md.
Propón casos de prueba para los 3 archivos principales.
"

Combínalo con Generación automática de tests para un impacto acumulativo.

6. Hacer visible el pago con informes semanales

Sin visibilidad, los equipos se rinden.

claude -p "
Informa sobre el pago de deuda técnica de la última semana:

- Elementos resueltos (revisa docs/tech-debt/backlog.md)
- Nueva deuda descubierta
- Elementos de severidad 5 aún abiertos
- Progreso de actualizaciones de dependencias

Salida a docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md.
Ajustado para una lectura de 5 minutos en el standup.
"

Prográmalo con cron los lunes por la mañana para institucionalizar el pago.

7. Detener nueva deuda en la puerta

El pago es inútil si la entrada continúa. Codifica reglas en CLAUDE.md.

## Reglas para prevenir nueva deuda técnica

### Prohibido
- Nuevos valores tipados como any (usa // @ts-expect-error con razón si es inevitable)
- Lógica provisional sin un TODO
- Lógica de negocio sin tests

### Checklist de PR
- [ ] Cobertura del nuevo código ≥ 80 %
- [ ] Cero errores de ESLint
- [ ] Adiciones de dependencias justificadas en el PR

### Excepciones aceptables
- Hotfixes (con ticket de seguimiento)
- Código POC (debe reescribirse antes de producción)

Fuerza su cumplimiento mediante pre-commit hooks. Consulta la Guía de Hooks.

Anti-patrones

❌ Un PR gigante de refactor

Los PRs que “arreglan todo” son irreprochables. Un smell = un PR.

❌ Mezclar cambios de comportamiento

Nunca combines trabajo de features con refactoring en el mismo PR. La carga de revisión se duplica.

❌ Refactorizar sin tests

Si la cobertura es baja, escribe primero los tests, luego refactoriza. Sin red de seguridad aparecen nuevos bugs.

Conclusión

• Usa Claude Code para exponer smells, deuda de dependencias y brechas de cobertura
• Cuantifica la prioridad con ICE scoring
• Divide el pago en PRs pequeños
• Publica informes semanales de progreso
• Bloquea nueva deuda mediante reglas en CLAUDE.md
• Un smell = un PR

La deuda técnica no es algo que arreglar “algún día”. Es algo que saldar un poco cada semana. Claude Code reduce drásticamente el coste de esa cadencia.

Relacionado: Automatización de refactoring / Modernización de código legacy / Checklist de code review

Documentación oficial: Anthropic Claude Code