Construí con IA un toolkit de refactorización para proyectos web este paso no debería ser opcional
Llevo un tiempo trabajando en protocolos de auditoría para proyectos web. Auditorías de performance, accesibilidad, SEO, seguridad — el tipo de revisiones que idealmente deberían pasar todos los proyectos antes de ir a producción. Pero había un eslabón que me faltaba: la refactorización.
No la refactorización cosmética de renombrar variables. Me refiero a la auditoría profunda — encontrar código muerto, duplicaciones sistemáticas, handlers sin autenticación, patrones inconsistentes, validaciones que solo existen en el cliente. El tipo de problemas que se acumulan silenciosamente mientras estamos enfocados en que las cosas «funcionen».
Y aquí es donde se pone interesante: muchos de estos problemas los estamos creando más rápido que nunca, precisamente porque construimos con IA.
El problema real: velocidad sin revisión
No me malinterpreten — las herramientas de IA para desarrollo son increíbles. Puedo generar en minutos lo que antes tomaba horas. Pero hay un lado B que no siempre reconocemos: el código generado por IA funciona, pero no siempre es limpio, consistente, ni seguro.
Cuando le pido a un agente que construya un módulo de autenticación, funciona. Cuando le pido que agregue un CRUD para otra entidad, también funciona. Pero el módulo de autenticación maneja errores de una forma, y el CRUD de otra. Las queries al servidor se hacen de tres maneras diferentes. Hay validaciones en el cliente pero no en el servidor. Y de repente tengo un proyecto que hace todo lo que necesito, pero cuyo código interno es un rompecabezas.
Multiplicado por semanas de desarrollo, esto se convierte en deuda técnica real. Y la diferencia entre un prototipo funcional y un producto mantenible es exactamente esa revisión que casi nadie hace.
La idea: convertir la auditoría en una skill reutilizable
Ya tenía experiencia creando Agent Skills — herramientas que los agentes de IA pueden usar para ejecutar tareas especializadas siguiendo el estándar abierto de agentskills.io. Había creado skills para auditorías de performance, accesibilidad, diseño visual. Así que la pregunta natural era: ¿puedo hacer lo mismo para refactorización?
Tenía unos prompts que venía usando para auditar mis propios proyectos. Cuatro fases secuenciales: análisis estructural, calidad de código, seguridad, y finalmente un plan de ejecución. Funcionaban bien, pero tenían un problema — estaban amarrados a un stack específico (Next.js, Supabase, Tailwind). Si quería que esto le sirviera a la comunidad, necesitaba hacerlos agnósticos.
El proceso de construcción
Lo primero fue analizar cuánto de mis prompts era realmente específico al stack. Resultó que alrededor del 85-90% del contenido era universal — principios de ingeniería de software que aplican igual en Laravel, Django, Rails o Express. Las referencias a Server Actions, Supabase y shadcn eran solo el 10-15%. Pero convertir prompts sueltos en una skill de calidad no es solo cambiar palabras. Hubo varias decisiones de diseño importantes.
Una skill o dos. Las primeras tres fases son diagnóstico puro — el agente lee pero no toca nada. La fase cuatro modifica archivos. Mezclar lectura con escritura en una sola skill es un riesgo de seguridad y de usabilidad. Así que las separé: refactoring-audit para el diagnóstico, refactoring-execute para la acción. Esto permite que alguien use solo la auditoría para generar un reporte sin tocar código — útil si eres tech lead y quieres evaluar un proyecto sin cambiarlo.
Agnóstico de verdad. En lugar de crear «perfiles» por framework (un archivo para Next.js, otro para Laravel, otro para Django), usé lenguaje genérico universal. Donde antes decía «Server Actions», ahora dice «server-side data mutation handlers». Cuando el agente audita un proyecto de Django, automáticamente interpreta eso como views. En Rails, como controllers. Sin configuración extra, sin archivos de perfil que mantener.
Umbrales concretos. Uno de los problemas de mis prompts originales era que algunos criterios eran subjetivos: «nombres poco descriptivos», «funciones demasiado largas». En la skill final, todo tiene un número: funciones de más de 50 líneas, componentes de más de 200, anidación de más de 3 niveles, más de 20 usos de any en TypeScript. Esto elimina la ambigüedad y hace que los reportes sean consistentes.
Progressive disclosure. El estándar de Agent Skills recomienda que el archivo principal (SKILL.md) se mantenga bajo 500 líneas. Mis criterios detallados fácilmente superaban eso. La solución fue progressive disclosure: el SKILL.md contiene la metodología y el flujo de ejecución (~120 líneas), y los criterios detallados de cada fase viven en archivos de referencia que el agente carga solo cuando los necesita.
Qué audita exactamente
El toolkit cubre tres dimensiones:
Fase 1 — Estructura. Organización de archivos y carpetas, código muerto (archivos, funciones, imports, variables que nadie usa), salud de dependencias (paquetes no usados, duplicados, con vulnerabilidades), y separación de responsabilidades (¿la lógica de negocio está donde debería estar?).
Fase 2 — Calidad. Duplicación de código, nomenclatura y legibilidad, complejidad excesiva (funciones gigantes, anidación profunda, ternarios encadenados), y consistencia de patrones (¿el manejo de errores es igual en todo el proyecto, o cada archivo lo hace diferente?).
Fase 3 — Seguridad y robustez. Autenticación y autorización en handlers del servidor, validación de inputs (¿existe en cliente Y servidor, o solo en uno?), manejo de errores completo (¿los errores se capturan, se loguean, se comunican al usuario correctamente?), e indicadores de cobertura de tests.
El reporte consolida todo con severidades claras: 🔴 Crítico (riesgo inmediato), 🟡 Importante (afecta mantenibilidad), 🟢 Menor (oportunidad de mejora).
Después, la skill de ejecución toma ese reporte, genera un plan priorizado (seguridad primero, siempre), y ejecuta los cambios de forma incremental — siempre esperando tu confirmación antes de tocar una sola línea de código.
Lo que aprendí en el camino
La evaluación importa tanto como la creación. Después de generar las skills, las pasé por una evaluación de 5 capas: compliance con la especificación, calidad de instrucciones, auditoría de seguridad, recomendaciones estructurales y veredicto final. Esto encontró tres mejoras que no habría detectado solo leyendo el código: faltaba un fallback cuando no hay reporte de auditoría, los ejemplos de output ayudan al agente a calibrar el formato, y el warning de version control necesitaba reforzarse para acciones de alto riesgo.
Separar diagnóstico de ejecución es una best practice. No solo por seguridad — también por reutilización. El reporte de auditoría puede servir como documento para un code review, como input para una reunión de equipo, o como base para un plan de sprint. No todo necesita ejecutarse inmediatamente.
Los umbrales eliminan discusiones. Cuando un criterio es «funciones demasiado largas», cada persona tiene una opinión diferente. Cuando es «funciones de más de 50 líneas», la discusión se acabó. Esto aplica tanto para agentes de IA como para equipos humanos.
Cómo usarlo
El toolkit está publicado como open source y disponible en el directorio de skills.sh. Lo puedes instalar con un solo comando:
npx skills add magallon/refactoring-toolkit --all
O instalar cada skill por separado:
npx skills add magallon/refactoring-toolkit --skill refactoring-audit
npx skills add magallon/refactoring-toolkit --skill refactoring-execute
Funciona con Claude Code, Cursor, Windsurf, Codex, OpenCode y más de 30 agentes compatibles. Es agnóstico al stack — funciona con cualquier proyecto web.
El repositorio completo está en GitHub: github.com/magallon/refactoring-toolkit
Si estás construyendo proyectos con IA, la refactorización no es un lujo ni algo que «haremos después». Es el paso que convierte un prototipo que funciona en un producto que se puede mantener, escalar y en el que puedes confiar.
La IA nos da velocidad. La refactorización nos da calidad. Y las dos juntas son lo que realmente necesitamos para ir a producción con confianza.
