Reducir deuda técnica con Claude Code: guía segura para equipos

Todos los equipos dicen que quieren reducir la deuda técnica. Luego llega el sprint, entran nuevas funcionalidades, y lo pendiente queda igual: más any, dependencias atrasadas, tests que fallan de vez en cuando y TODOs que nadie se atreve a tocar.

Claude Code no convierte el refactoring automático en algo sin riesgo. Su valor real es más concreto: ayuda a inventariar deuda, añadir evidencia, priorizar y dividir el pago en PR pequeños y revisables. Esa diferencia convierte una limpieza peligrosa en una práctica semanal.

Esta guía cubre inventario de code smells, deuda de dependencias, flaky tests (tests inestables), lógica duplicada, TODOs peligrosos, priorización con ICE/RICE, estrategia de PR pequeños y gobernanza. Como base oficial, revisa Common workflows, Memory y Settings. También puedes complementar con estrategias de testing, buenas prácticas de CLAUDE.md y la guía de aprobación y sandbox.

Convertir la deuda en un ciclo de pago

El error habitual es tratar la deuda como una gran limpieza. La rama crece, la revisión se vuelve imposible y nadie puede confirmar si el comportamiento cambió.

Usa un ciclo corto.

flowchart LR
  A["Inventario"] --> B["Evidencia"]
  B --> C["Puntuación ICE/RICE"]
  C --> D["PR pequeños"]
  D --> E["Tests y revisión"]
  E --> F["Actualizar registro"]
  F --> A

El inventario no debe basarse en sensaciones. Reúne rutas de archivo, líneas, logs de CI, paquetes obsoletos, usos de any, archivos grandes, lógica duplicada y comentarios TODO/FIXME.

Enfoque	Sirve para	Riesgo	Cómo ayuda Claude Code
Refactor grande	Migraciones con límites claros	Diff imposible de revisar	Investigación y plan de migración
PR pequeños de deuda	Mantenimiento continuo	El impacto parece pequeño	Registro, scoring y checklist
Sprint de dependencias	Seguridad y paquetes EOL	Cambios incompatibles ocultos	Resumen de changelog y plan de tests
Limpieza de flaky tests	CI perdió credibilidad	Reintentar oculta bugs reales	Clasificación y pasos de reproducción

Caso 1: inventariar code smells

Un code smell no siempre es un bug. Es una señal de que los cambios futuros serán más difíciles: funciones gigantes, clases con demasiadas responsabilidades, validaciones duplicadas, números mágicos o escapes del sistema de tipos.

Primero pide inspección, no edición.

claude -p "
Inspecciona src/ y tests/ para encontrar deuda técnica. No edites archivos todavía.

Busca:
- Funciones de más de 80 líneas
- Archivos de más de 300 líneas
- Anidamiento de más de 4 niveles
- Validación, manejo de fechas o permisos duplicados
- TypeScript any, as any y @ts-ignore
- Comentarios TODO / FIXME / HACK
- Ramas sin tests o tests que solo verifican renderizado

Devuelve una tabla Markdown que pueda pegar en docs/tech-debt/register.md.
Columnas: ID, File, Line, Debt type, Evidence, Risk, Suggested first PR, Confidence.
"

La frase “No edites archivos todavía” evita cambios especulativos. Deja que Claude Code investigue y clasifique; el equipo decide qué deuda pagar primero.

Caso 2: detectar deuda de dependencias

Bibliotecas obsoletas, paquetes sin mantenimiento, vulnerabilidades y duplicación de librerías también son deuda. Contar avisos de npm audit no basta: puede distraer de un paquete central cercano al fin de vida.

claude -p "
Con package.json, lockfile, npm outdated y npm audit, clasifica la deuda de dependencias.

Categorías:
1. Requiere corrección de seguridad
2. Requiere major update con posibles breaking changes
3. Sin mantenimiento o con reemplazo recomendado
4. Librerías duplicadas para el mismo trabajo
5. Seguro de posponer

Para cada elemento, lista área de impacto, changelog que leer primero, tests requeridos y el PR seguro más pequeño.
Separa cambios automatizables de cambios que requieren revisión humana.
"

Una dependencia no es segura solo porque los tests pasen una vez. Fechas, auth, criptografía, routing, herramientas de build y runners de test merecen ramas aisladas y notas de rollback.

Caso 3: pagar flaky tests y lógica duplicada

Los flaky tests destruyen la confianza. Cuando el equipo cree que “si reintentamos pasará”, la suite deja de ser una red de seguridad.

claude -p "
Lee los últimos 20 logs de fallos de CI y clasifica posibles flaky tests.

Clasifica por:
- Dependencia de hora, zona horaria o datos aleatorios
- Dependencia de red o API externa
- Estado compartido que se filtra entre tests
- Esperas asíncronas inestables
- Probable bug de producto que no debe etiquetarse como flaky

Para cada candidato, da comando de reproducción, arreglo mínimo y assertion a añadir.
"

Con la lógica duplicada, el primer PR debe ser aburrido. Si el chequeo de permisos está copiado en cuatro archivos, extrae un helper puro y fija el comportamiento con tests. Cambia los call sites uno por uno en PR posteriores.

Script copiable para escanear deuda

Claude Code ayuda a analizar, pero los marcadores mecánicos deben poder repetirse. Guarda esto como scripts/debt-scan.mjs y ejecuta node scripts/debt-scan.mjs src.

import fs from "node:fs";
import path from "node:path";

const root = process.argv[2] || "src";
const maxLines = Number(process.env.MAX_LINES || 300);
const extensions = new Set([".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs"]);
const findings = [];

function walk(dir) {
  if (!fs.existsSync(dir)) return;

  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const fullPath = path.join(dir, entry.name);

    if (entry.isDirectory()) {
      if ([".git", "node_modules", "dist", "build", ".next", "coverage"].includes(entry.name)) continue;
      walk(fullPath);
      continue;
    }

    if (entry.isFile() && extensions.has(path.extname(entry.name))) {
      scanFile(fullPath);
    }
  }
}

function add(file, line, type, severity, detail) {
  findings.push({ file, line, type, severity, detail });
}

function scanFile(file) {
  const text = fs.readFileSync(file, "utf8");
  const lines = text.split(/\r?\n/);

  if (lines.length > maxLines) {
    add(file, 1, "large-file", 3, `${lines.length} lines`);
  }

  lines.forEach((line, index) => {
    const lineNumber = index + 1;

    if (/\b(FIXME|TODO|HACK)\b/i.test(line)) {
      add(file, lineNumber, "unsafe-comment", /FIXME|HACK/i.test(line) ? 4 : 3, line.trim());
    }

    if (/\.(ts|tsx)$/.test(file) && /(:\s*any\b|as\s+any\b|<any>)/.test(line)) {
      add(file, lineNumber, "typescript-any", 4, line.trim());
    }
  });
}

walk(root);

console.log("| file | line | type | severity | detail |");
console.log("| --- | ---: | --- | ---: | --- |");
for (const item of findings.sort((a, b) => b.severity - a.severity || a.file.localeCompare(b.file))) {
  const detail = item.detail.replaceAll("|", "\\|");
  console.log(`| ${item.file} | ${item.line} | ${item.type} | ${item.severity} | ${detail} |`);
}

if (findings.length === 0) {
  console.error("No obvious debt markers found.");
}

No detecta arquitectura ni toda la duplicación. Aun así, da una línea base semanal para TODO, FIXME, any y archivos grandes.

Plantilla de registro de deuda

Antes de crear issues, junta los hallazgos en un registro.

# Technical Debt Register

| ID | Area | Evidence | User or team impact | ICE | RICE | Owner | Next PR | Status |
| --- | --- | --- | --- | ---: | ---: | --- | --- | --- |
| TD-001 | Auth permissions | src/auth/guard.ts duplicates role checks in 4 places | New role changes take 2 days and often miss one path | 420 | 1680 | Backend | Extract pure canAccess() with tests | Ready |
| TD-002 | Dependencies | vite is 2 major versions behind | Security patches and plugin updates are blocked | 280 | 900 | Platform | Upgrade in isolated branch and run build/test | Investigating |

## Scoring note

- ICE = Impact x Confidence x Ease
- RICE = Reach x Impact x Confidence / Effort
- Keep evidence links concrete: file path, line, CI run, or user-facing incident.

ICE es rápido para ordenar. RICE es mejor cuando necesitas incluir alcance y esfuerzo. Ninguno es una verdad absoluta: son herramientas para alinear conversaciones.

Prompt para un plan de refactor seguro

Cuando el equipo elija una deuda, pide un plan antes de editar.

claude -p "
Crea un plan seguro para pagar TD-001. No edites archivos todavía.

Alcance:
- src/auth/guard.ts
- src/auth/roles.ts
- tests/auth/guard.test.ts

Restricciones:
- No cambiar comportamiento de API externa
- Revisar tests existentes primero
- Si falta cobertura de comportamiento, añadir characterization tests antes del refactor
- Apuntar a un PR de menos de 300 líneas cambiadas
- Incluir riesgos, rollback y foco para reviewers

Salida:
1. Resumen del comportamiento actual
2. Non-goals explícitos
3. Plan del primer PR
4. Comandos de test
5. Mensaje de solicitud de review
"

Los non-goals evitan que el cambio crezca. Claude Code suele ayudar de más si no delimitas el PR.

Checklist de PR de refactor

## Refactor PR checklist

- [ ] This PR changes structure, not product behavior.
- [ ] Existing behavior is covered by tests before the refactor.
- [ ] New helper names describe domain behavior, not implementation detail.
- [ ] Public API, response shape, permissions, and logging are unchanged or explicitly documented.
- [ ] The diff is small enough to review in one sitting.
- [ ] Rollback is simple: revert this PR without reverting unrelated work.
- [ ] The debt register is updated with status and follow-up PRs.

Inclúyelo en el cuerpo del PR que redacte Claude Code. Convierte “confía, solo es refactor” en evidencia revisable.

Errores concretos

Confiar demasiado en la automatización Que TypeScript compile no basta. Autorización, pagos, fechas, asincronía y migraciones requieren tests de caracterización y revisión humana.

Borrar todos los TODO Algunos son bloqueantes de release y otros simples notas. Prioriza remove before release, bypass auth, temporary token y FIXME.

Agrupar muchas actualizaciones Diez major updates en un PR hacen muy difícil aislar fallos. Separa build tools, UI, auth y test runners.

Usar puntuaciones como política ICE/RICE debe llevar evidencia: rutas, logs de CI, incidentes y supuestos de esfuerzo.

No dejar memoria de equipo Reglas como “código de permisos requiere aprobación” o “refactors bajo 300 líneas” deben vivir en CLAUDE.md o settings. Memory y Settings reducen prompts repetidos.

Gobernanza para equipos

Una cadencia práctica es una revisión semanal de 30 minutos:

1. Revisar el escáner y el inventario de Claude Code.
2. Actualizar ICE/RICE solo para los 10 primeros.
3. Elegir un PR de pago para el siguiente sprint.
4. Elevar prioridad de flaky tests y dependencias de seguridad.
5. Registrar qué se volvió más fácil tras el PR.

ClaudeCodeLab ayuda a convertir esto en un sistema real: plantillas de registro, checklists de PR, settings y reglas iniciales de CLAUDE.md. Si quieres adaptarlo a tu repositorio y cultura de review, revisa training, templates and consultation de Claude Code.

Resumen

La forma segura de reducir deuda técnica con Claude Code no es pedirle que refactorice todo. Es reunir evidencia, puntuar, y pagar una deuda por PR pequeño. Code smells, dependencias, flaky tests, lógica duplicada y TODOs peligrosos caben en el mismo ciclo.

Al probar este flujo en proyectos pequeños de Masa, el mayor beneficio fue separar la deuda urgente de la que solo debía registrarse. Dividir la limpieza de any y TODOs antiguos en PR pequeños redujo riesgo sin aumentar mucho la carga de review. Las major updates de dependencias fueron más pesadas de lo esperado, así que fue más seguro añadir tests y notas de release antes de pedir a Claude Code los cambios.