¿Cómo abordar un refactor con IA: pedirlo directamente o preparar el contexto antes?
Pedirle a un agente "hazme un refactor" sin más suele salir mal. El primer paso real es el mismo que en cualquier tarea de SDD: invertir tiempo en que el contexto sepa cómo debe hacerse ese refactor antes de ejecutarlo.
La pregunta real
Ante una base de código que necesita un refactor, es habitual dudar entre dos caminos: pedirle directamente al agente "hazme un refactor de este módulo" y confiar en su criterio, o invertir tiempo antes en preparar el contexto que guíe ese refactor. ¿Cuál de los dos enfoques da resultados más fiables?
La respuesta es la misma que para cualquier otra tarea dentro de Spec-Driven Development: el primer paso nunca es pedir el resultado final directamente, es asegurarse de que el contexto sabe cómo debe hacerse ese tipo de cambio antes de ejecutarlo.
Por qué "hazme un refactor" sin más suele fallar
Un refactor es, por definición, un cambio donde el comportamiento externo debe mantenerse igual mientras cambia la estructura interna. Sin restricciones explícitas, un agente no tiene forma de saber qué parte de esa estructura interna es intencional (una decisión de arquitectura que hay que respetar) y cuál es simplemente deuda técnica que puede tocar libremente. El resultado típico de pedir un refactor sin contexto previo es que el agente aplique su propio criterio genérico —que puede no coincidir en absoluto con las convenciones reales del proyecto— o que se quede corto, tocando solo lo superficial por miedo a romper algo que no entiende del todo.
Definir la dirección antes de pedir nada
Qué patrón de destino se persigue, qué debe conservarse tal cual y qué librerías o convenciones deben respetarse — todo esto en una regla o documento, no en la primera línea del prompt.
Crear un comando de refactor propio del producto
En lugar de depender de una instrucción genérica de "refactoriza esto", un comando específico ya conoce las restricciones concretas de ese repositorio y las aplica de forma consistente cada vez que se invoca.
Apoyarse en herramientas de análisis del código cuando existan
Un MCP orientado al árbol de sintaxis puede acelerar la parte mecánica del refactor (localizar referencias, renombrar), pero no sustituye tener claro de antemano qué dirección debe tomar el cambio.
Un comando de refactor, no un prompt suelto
La forma más robusta de aplicar esto en la práctica es convertir "cómo hacemos un refactor en este proyecto" en un comando reutilizable y específico del producto, no un comando genérico copiado de otro repositorio. Ese comando ya sabe, por ejemplo, que las validaciones de negocio no deben moverse de capa, que ciertos módulos son intocables por estar compartidos con otro equipo, o que cualquier cambio de estructura tiene que venir acompañado de la actualización de los tests existentes antes de darse por completo. Al ejecutarlo, el agente parte de esas restricciones ya resueltas, en vez de tener que inferirlas leyendo el repositorio entero cada vez.
Cuándo esto importa más
Preparar el contexto antes de pedir un refactor importa especialmente en código compartido entre varias personas o equipos, donde una decisión de estructura equivocada no se queda contenida en un solo módulo. En un prototipo personal o un script de un solo uso, el coste de definir todo ese contexto puede no compensar frente a simplemente pedir el cambio y revisar el resultado a mano.
El criterio general: cuanto mayor es el radio de impacto de un refactor mal dirigido, más justificado está invertir tiempo por adelantado en dejar esas restricciones explícitas antes de ejecutarlo.
Resumen rápido
- Pedir un refactor sin contexto previo deja que el agente decida solo qué es "intencional" y qué es deuda técnica, con resultados poco predecibles.
- Definir de antemano qué mantener, qué dirección seguir y qué librerías usar es el mismo primer paso que en cualquier tarea de Spec-Driven Development.
- Un comando de refactor específico del producto (no genérico) evita repetir esas restricciones cada vez y hace el proceso reproducible.
¿Quieres aplicar esto en tu equipo?
En Kuuli Technologies llevamos estas metodologías a equipos reales. Escríbenos si quieres una sesión de trabajo o una consultoría sobre agentes IA y SDD.