Refactorizar código heredado es uno de esos trabajos que todo desarrollador pospone hasta que ya no hay forma de esquivarlo. El código funciona, más o menos, pero nadie quiere tocarlo porque nadie sabe bien qué hace ni por qué. Entran la IA y las expectativas infladas: «le pego el código, me da el código limpio, listo». No funciona así.
Lo que sí funciona es usarla como herramienta de proceso, no como reemplazo del criterio. Hoy comparto la metodología que aplico la mayoría de las veces.
Antes de cualquier cosa: evalúa qué le estás pasando al modelo
El código de un cliente no es tuyo para compartirlo sin criterio. Antes de pegar cualquier función en Claude, hay una pregunta obligatoria: ¿qué tan sensible es este código?
Revisa si contiene lógica de negocio que identifique al cliente, nombres de variables o comentarios que revelen el dominio, datos de configuración, credenciales, o cualquier cosa que no debería salir del proyecto. Si alguna de esas condiciones se cumple, el código no va a un modelo externo en esa forma. Se anonimiza, se abstrae, o se busca otra vía.
Si el código es una función de utilidad sin referencias al negocio, sin comentarios comprometedores y sin datos sensibles, adelante. Pero ese juicio lo haces tú antes de empezar, no después.
Antes de tocar una sola línea: el diagnóstico
El primer paso no es documentar ni generar pruebas. Es sentarse con Claude Opus, el modelo más potente de la familia, y contarle todo lo que ya sabes sobre el problema. Es como que vas con el chisme a ver que ideas te puede dar, y casi siempre no se trata de lo que dice que hay que hacer si no de lo que pregunta, esa pregunta que a ti mismo se te escapo hacer. A claude Opus no le vas a hablar el del código si no del problema.
¿Qué hace ese módulo? ¿Por qué está tan enredado? ¿Hubo migraciones a medias, decisiones de negocio que obligaron a parcharlo, un desarrollador que se fue sin documentar nada? ¿Hay partes que no se pueden tocar porque el cliente no sabe bien qué hacen pero teme que algo se rompa?
Con ese contexto completo, le pido a Opus su opinión sobre el enfoque. No instrucciones: opinión. Qué riesgos ve, qué orden sugiere, qué partes conviene aislar primero. Esta conversación inicial vale más que cualquier prompt de generación de código. Es el mapa antes de entrar al territorio.
Uso Opus específicamente para esta fase porque la complejidad conceptual del diagnóstico requiere el modelo con mayor capacidad de razonamiento. Para la generación de código en los pasos siguientes, Sonnet es suficiente y más eficiente.
Paso 1: Documentar lo que existe
Antes de refactorizar, necesito entender. Y antes de entender, necesito documentación.
Le paso la función o módulo a Claude Sonnet y le pido que genere documentación: propósito, parámetros de entrada, valores de retorno, comportamiento en casos borde. La primera versión casi siempre tiene errores. El modelo infiere el propósito desde el código, y si el código es confuso, la documentación también lo será.
Ahí entra mi trabajo: revisar esa documentación contra el código real, contrastar con los puntos donde se llama esa función, corregir lo que está mal y pedirle a Claude que ajuste. La segunda versión ya es útil.
Este paso no es opcional. Refactorizar sin documentar primero es reemplazar un problema que entiendes a medias por otro que no entiendes nada.
Paso 2: Frontend primero, casi siempre
Cuando el proyecto tiene interfaz, empiezo por ahí. No porque sea más fácil, sino porque es lo que el cliente puede ver.
Un cliente ansioso necesita evidencia de avance. Si paso tres días ordenando la lógica del backend sin que nada cambie visualmente, la percepción es que no ha pasado nada. Si en cambio mejoro primero la capa de presentación, el componente que cargaba en cuatro segundos ahora carga en uno, el código del template dejó de ser un desastre de condicionales anidados, el cliente respira. Y cuando respira, tengo más margen para trabajar en calma en lo que realmente importa.
La refactorización del frontend también sirve como laboratorio: si el proceso funciona ahí, con partes visibles y fáciles de verificar, puedo ajustar el flujo antes de meterme en la lógica de negocio.
Paso 3: Pruebas antes del código refactorizado
Antes de pedirle a Claude que genere código simplificado, necesito pruebas del comportamiento actual.
Le pido a Sonnet que genere pruebas unitarias basadas en la documentación que ya validamos. La instrucción es clara: las pruebas deben cubrir el comportamiento del código original, no un comportamiento ideal. Si el código tiene quirks, las pruebas los capturan.
Aquí hay un punto crítico: las pruebas van a fallar en el código original con cierta frecuencia, especialmente si Claude malinterpretó algo del propósito de la función. Eso es información útil, no un fracaso. Corrijo las pruebas, no el código. El código original es la referencia.
Cuando tengo un conjunto de pruebas que pasan contra el código original, tengo una red de seguridad. Recién ahí le pido el código refactorizado.
Paso 4: Generar el código simplificado
Le pido a Claude Sonnet que proponga opciones de simplificación, no una sola solución. Generalmente da dos o tres enfoques con distintos estilos: uno más funcional, uno más explícito, uno más compacto. Todos comparten la lógica general pero difieren en cómo la expresan.
La tentación es elegir el que parece más elegante. El criterio correcto es elegir el que sea más fácil de mantener por alguien que no estuvo en esta conversación.
Corro las pruebas contra cada opción. El código de Claude raramente pasa todo desde el primer intento. Los errores más comunes son confusiones entre nombres de variables y sus valores, o simplificaciones que perdieron un caso borde. Los detecto con el depurador, los corrijo yo mismo si son simples, o le explico el problema a Claude si requieren regenerar una sección.
El flujo es: ejecutar pruebas, depurar lo que falla, corregir o pedir corrección, repetir. No es automático. Es iterativo.
Paso 5: Limpieza final, sin delegar
El código que sale de Claude mantiene en general la nomenclatura original de las variables. Eso está bien como punto de partida, pero la limpieza final es trabajo mío.
Renombro variables según el entendimiento que desarrollé durante el proceso. Elimino comentarios redundantes, añado los que faltan. Simplifico secuencias que quedaron más complejas de lo necesario. Reviso que el estilo sea consistente con el resto del proyecto.
Esta fase no se le delega a la IA. El criterio sobre qué nombre comunica mejor, qué comentario aporta y cuál estorba, qué nivel de abstracción es apropiado para este equipo específico, ese criterio es mío.
Modelo de IA recomendado por tipo de tarea
Ahora si no hay un cliente a quien responder elige el método que mejor se ajuste al flujo de trabajo.
Primero lo que no cambia comportamiento:
Limpia el código muerto y renombra antes de pasarle nada a ningún modelo, porque cada línea innecesaria que entra al contexto es un token que pagas de más y ruido que aumenta la probabilidad de error.
Haiku es el modelo mas económico y que consume menos tokens. Mucha gente utiliza los modelos de menor consumo para este tipo de tareas pensando que es mas que suficiente. Pero la eliminación de código muerto y el renombrado no son tareas que se hagan en el vacío. Requieren entender el contexto del código para saber si algo realmente está muerto o si ese nombre realmente no describe bien la intención. Haiku puede equivocarse en ese juicio con más frecuencia que Sonnet, y un falso positivo en «código muerto» borra algo que sí se usaba.
El renombrado en cascada, la eliminación de imports sin uso, borrar bloques comentados que nadie va a restaurar, eso lo puedes hacer tu con las herramientas del entorno de desarrollo, un poco de trabajo manual no va a matar a nadie, ya lo hacías antes de que apareciera la IA.
Luego lo estructural:
Apartir de aqui utiliza Sonnet.
- Extracción de método: Aquí empieza el trabajo real. Identificar los bloques que hacen una cosa concreta.
- Simplificación de condicionales: Esto va después de la extracción porque a veces los condicionales complejos se simplifican solos cuando extraes partes a métodos propios.
Al final lo que mueve responsabilidades:
- Reemplazar variable temporal con consulta.
- Mover características entre objetos: Esto es el cambio de mayor impacto estructural y el de mayor riesgo. Va al final, cuando ya entiendes bien qué hace cada parte y tienes pruebas que te respaldan. En algunos casos podría requerir el modelo de mayor razonamiento.
Una nota sobre otras herramientas
He visto propuestas de usar Gemini para este tipo de trabajo. Ni loco. No es una cuestión de prejuicio, es una cuestión de historial: para tareas que requieren mantener contexto complejo a lo largo de múltiples iteraciones y razonar sobre código con muchas interdependencias, Claude tiene un desempeño significativamente más consistente. Puedes ver mi análisis más detallado en la comparativa entre Claude Code, Gemini CLI y Qwen Code.
Lo que la IA reduce y lo que no
- Lo que la IA reduce: el tiempo de generación de documentación inicial, el tiempo de escritura de pruebas, el tiempo de producir un primer borrador del código refactorizado, y la probabilidad de quedarte atascado en un enfoque único.
- Lo que la IA no reduce: el tiempo que necesitas para entender el código original, el tiempo de depuración, el criterio necesario para validar cada output. Si no entiendes lo que el modelo te entrega, no puedes saber si está bien.
El resultado final depende del desarrollador que conduce el proceso, no del modelo que genera el código. Claude para la refactorización de código es una herramienta potente. Pero sigue siendo una herramienta, y las herramientas no piensan por ti.
El 90% de programar se basa en leer código. Y eso es algo que no ha cambiado con la IA.
Si te interesa explorar más sobre inteligencia artificial aplicada al desarrollo, hay casos concretos documentados en el blog.