refactor
npx machina-cli add skill 686f6c61/alfred-dev/refactor --openclawRefactorizar código
Resumen
Este skill guía un proceso de refactorización seguro. La regla de oro es que la refactorización nunca cambia el comportamiento observable del sistema, solo mejora su estructura interna. Para garantizar esto, los tests existentes actúan como red de seguridad: deben pasar antes, durante y después de la refactorización.
La refactorización y la adición de funcionalidad son dos actividades distintas que nunca se mezclan en el mismo commit. Si se detecta un bug durante la refactorización, se anota y se corrige en un commit separado.
Proceso
-
Identificar el code smell. Antes de refactorizar, tener claro qué problema se está resolviendo. Los code smells más comunes son:
- Funciones demasiado largas (más de 30 líneas).
- Parámetros excesivos (más de 3).
- Duplicación de lógica.
- Condicionales anidados profundamente.
- Nombres poco descriptivos.
- Clases con demasiadas responsabilidades.
- Acoplamiento excesivo entre módulos.
- Comentarios que compensan código confuso (mejor reescribir el código).
-
Verificar que los tests pasan ANTES de empezar. HARD-GATE: ejecutar la suite de tests completa (o al menos los tests del módulo afectado) y confirmar que todo está en verde. No se refactoriza sobre una base rota.
-
Si no hay tests suficientes, escribirlos primero. Si el área a refactorizar no tiene cobertura de tests, escribir tests de caracterización que capturen el comportamiento actual antes de cambiar nada. Estos tests se commitean por separado.
-
Aplicar la refactorización en pasos pequeños. Cada paso debe ser:
- Lo bastante pequeño como para ser reversible.
- Verificable con los tests existentes.
- Comprensible de forma aislada.
Técnicas comunes: extraer función, renombrar, mover a módulo, introducir parámetro, reemplazar condicional con polimorfismo, simplificar expresión.
-
Ejecutar tests después de cada paso. No acumular múltiples cambios sin verificar. Si un test se rompe, deshacer el último paso y analizar por qué.
-
Verificar que los tests SIGUEN pasando al final. Ejecutar la suite completa una última vez. Comparar el comportamiento observable: mismos inputs deben producir mismos outputs.
-
Hacer commit separado. El commit de refactorización va aparte del commit de nueva funcionalidad. Mensaje descriptivo:
refactor: extraer lógica de validación a módulo independiente.
Criterios de éxito
- Los tests pasan antes y después de la refactorización.
- El comportamiento observable del sistema no ha cambiado.
- El code smell identificado se ha eliminado o reducido.
- El commit de refactorización no incluye nueva funcionalidad.
- El código resultante es más legible, mantenible o simple que el anterior.
Source
git clone https://github.com/686f6c61/alfred-dev/blob/main/skills/desarrollo/refactor/SKILL.mdView on GitHub Overview
Este skill guía una refactorización segura: el comportamiento observable permanece igual y los tests actúan como red de seguridad. Se enfatiza que la refactorización y la adición de funcionalidad deben ir en commits separados. Se recomienda verificar los tests antes, durante y después del proceso para evitar regresiones.
How This Skill Works
Se identifica el code smell y se verifica que la suite de tests esté verde antes de empezar (Hard-Gate). Si no hay tests suficientes, se añaden tests de caracterización y se comiten por separado. Luego se aplican cambios en pasos pequeños, verificando con los tests tras cada paso, y al final se ejecuta la suite completa y se registra un commit de refactorización descriptivo.
When to Use It
- Cuando una función es demasiado larga (más de 30 líneas) y dificulta la comprensión.
- Cuando hay más de 3 parámetros y se puede reducir la complejidad.
- Cuando se duplica lógica o hay condicionales anidados profundamente.
- Cuando hay nombres poco descriptivos o clases con demasiadas responsabilidades.
- Cuando no existe cobertura de tests y se necesita seguridad de comportamiento antes de refactorizar.
Quick Start
- Step 1: Identifica el code smell y verifica que la suite de tests esté verde (Hard-Gate).
- Step 2: Si no hay tests suficientes, escribe tests de caracterización y comítalos por separado.
- Step 3: Aplica refactorización en pasos pequeños, ejecuta tests tras cada paso y haz un commit descriptivo de refactor.
Best Practices
- Ejecuta la suite de tests completa (o al menos del módulo afectado) antes de empezar.
- Si no hay tests, escribe tests de caracterización y comítalos por separado.
- Realiza cambios en pasos pequeños que sean reversibles y verificables.
- Ejecuta tests tras cada paso y no acumules cambios sin verificación.
- Haz el commit de refactorización separado del commit de nueva funcionalidad, con un mensaje descriptivo.
Example Use Cases
- Extraer la lógica de validación a un módulo independiente para facilitar la reutilización y pruebas.
- Renombrar funciones y moverlas a módulos especializados para reducir acoplamiento.
- Reemplazar condicional con polimorfismo para simplificar rutas de ejecución.
- Simplificar expresiones complejas para mejorar legibilidad y mantenimiento.
- Eliminar duplicación de código mediante extracción de funciones reutilizables.
