Cómo automatizar la refactorización con Claude Code

¿Por qué refactorizar con Claude Code?

Todos saben que la refactorización es importante, pero hacerla manualmente es tedioso y a menudo se posterga. Claude Code entiende todo tu proyecto y puede ejecutar refactorizaciones de forma autónoma a través de múltiples archivos.

Patrón 1: Mejorar la seguridad de tipos

Eliminar tipos any

> Busca en el proyecto todos los tipos any y reemplázalos con tipos apropiados.
> Después de los cambios, verifica que npx tsc --noEmit pase correctamente.

Así es como Claude Code maneja esto:

1. Busca archivos que contengan tipos any
2. Infiere los tipos apropiados a partir del código circundante
3. Crea archivos de definición de tipos si es necesario
4. Ejecuta el verificador de tipos para confirmar que todo compila

Antes y después

// Antes
function processData(data: any): any {
  return data.items.map((item: any) => item.name);
}

// Después
interface DataPayload {
  items: Array<{ name: string; id: number }>;
}

function processData(data: DataPayload): string[] {
  return data.items.map((item) => item.name);
}

Patrón 2: Dividir funciones y clarificar responsabilidades

Dividir funciones demasiado grandes es algo que Claude Code maneja excepcionalmente bien.

> La función createOrder en src/services/orderService.ts tiene más de 200 líneas.
> Divídela en funciones más pequeñas siguiendo el principio de responsabilidad única.
> Asegúrate de que los tests existentes sigan pasando.

Prompt para dividir

> Divide la función usando estas directrices:
> - Cada función debe tener 30 líneas o menos
> - Separa validación, lógica de negocio y persistencia
> - Agrega comentarios JSDoc a cada función
> - Divide los tests para que correspondan a los nuevos límites de función

Patrón 3: Estandarizar el manejo de errores

Unifica los patrones de manejo de errores en todo tu proyecto.

> Estandariza el manejo de errores en todo el proyecto:
> - Usa una clase de error personalizada (AppError)
> - Define los códigos de error como constantes
> - Incluye siempre logging en los bloques try-catch

Este es un ejemplo de lo que genera Claude Code:

// src/errors/app-error.ts
export class AppError extends Error {
  constructor(
    public readonly code: string,
    message: string,
    public readonly statusCode: number = 500,
    public readonly cause?: Error
  ) {
    super(message);
    this.name = 'AppError';
  }
}

// Constantes de códigos de error
export const ErrorCodes = {
  USER_NOT_FOUND: 'USER_NOT_FOUND',
  INVALID_INPUT: 'INVALID_INPUT',
  DB_CONNECTION_ERROR: 'DB_CONNECTION_ERROR',
} as const;

Patrón 4: Agregar y mejorar tests

Agrega tests donde la cobertura es insuficiente.

# Usa reportes de cobertura para guiar la adición de tests
npx vitest run --coverage | claude -p "Identifica archivos con baja cobertura y agrega los casos de test faltantes"

> Lleva la cobertura de tests de todo lo que está en src/services/ al menos al 80%.
> Cubre no solo los caminos exitosos, sino también casos límite y escenarios de error.

Patrón 5: Estandarizar formatos de respuesta de API

> Estandariza todas las respuestas de los endpoints de API a este formato:
>
> Éxito: { success: true, data: T }
> Fallo: { success: false, error: { code: string, message: string } }
>
> Actualiza el código del frontend para que coincida con el nuevo formato.

Consejos para una refactorización segura

1. Verifica los tests primero

> Ejecuta npm test primero y asegúrate de que todos los tests existentes pasen.
> Si algún test falla, repórtalo antes de hacer cambios.

2. Trabaja de forma incremental

Refactoriza módulo por módulo en lugar de todo de una vez.

> Comienza refactorizando solo src/services/userService.ts.
> Verifica que los tests pasen después de los cambios antes de continuar.

3. Revisa el diff

> Muéstrame el git diff. Si es demasiado grande, resume los cambios por archivo.

4. Usa una rama separada

git checkout -b refactor/error-handling
claude
> Comienza la refactorización del manejo de errores...

Ejemplo real: Modernizar código heredado

Así puedes modernizar una base de código antigua de forma incremental:

> Moderniza este proyecto con los siguientes cambios:
> 1. Reemplaza var con const/let
> 2. Convierte funciones con callback a async/await
> 3. Convierte require a import
> 4. Verifica que los tests pasen después de cada cambio
> 5. Procede un paso a la vez y reporta resultados en cada etapa

Conclusión

Con Claude Code, la refactorización que antes tomaba días puede hacerse en horas. Las claves son: proporciona reglas específicas, trabaja de forma incremental y siempre valida con tests. Comienza con un módulo pequeño y comprueba los resultados por ti mismo.