Refactoring antes de AI: por qué los agentes amplifican el caos

Los agentes de AI amplifican la estructura que reciben. Un modelo de dominio limpio con estados explícitos, fronteras nombradas y restricciones documentadas se convierte en una superficie de automatización confiable. Un codebase desordenado con ownership ambiguo, transiciones de estado implícitas y conocimiento tribal se convierte en caos acelerado — los mismos bugs, los mismos tickets mal enrutados, las mismas respuestas incorrectas, ahora generadas a velocidad de inferencia en lugar de la velocidad de un ingeniero junior leyendo historial de Slack.

La industria ha cuantificado esto: la actividad de refactoring cayó un 60% desde que las herramientas de AI coding se masificaron, mientras que el code churn — líneas revertidas o reescritas en dos semanas — se duplicó. Los equipos generan más código y consolidan menos. La arquitectura se degrada más rápido porque nadie hace el trabajo estructural que mantiene un sistema navegable. El resultado son codebases donde los agentes de AI pasan tests pero violan la arquitectura, donde el código generado es comportamentalmente correcto pero estructuralmente incorrecto. Refactorizar antes de automatizar con AI es la intervención que rompe este ciclo.

La automatización magnifica la estructura — incluyendo la mala estructura

Los agentes de AI operan sobre los artefactos que pueden leer: código, configuración, documentación, definiciones de workflow. Cuando esos artefactos son claros, la salida del agente es predecible. Cuando son ambiguos, la salida del agente es confidencialmente incorrecta — y la confianza es lo que la hace peligrosa.

Un agente de automatización de soporte falla porque dos módulos definen "cliente" de forma diferente — uno se refiere a la entidad de facturación, el otro al usuario final. El agente resuelve un ticket actualizando el registro del cliente equivocado. Una automatización de workflow se rompe porque las reglas de escalación viven en un hilo de Slack que tres personas recuerdan pero ningún sistema codifica. El agente enruta tickets al equipo equivocado durante dos semanas antes de que alguien note el patrón.

Estos no son fallos de AI. Son fallos estructurales que existían antes de que el agente llegara. Un humano los navegaba mediante memoria institucional y cambio de contexto. El agente los navega mediante las únicas señales que tiene: el código, el schema, la configuración. Si esas señales son contradictorias, el comportamiento del agente es contradictorio — a escala, continuamente, sin fatiga ni autocuestionamiento.

Los agentes de AI necesitan fronteras de dominio estables para operar de forma segura

Un agente que modifica código necesita saber dónde empieza y termina un módulo. Un agente que enruta tickets necesita saber qué equipo es dueño de qué dominio. Un agente que genera reportes necesita saber qué definición de "revenue" aplica en qué contexto. Estos son domain boundaries — y en la mayoría de organizaciones, son implícitos, disputados, o diferentes según a quién preguntes.

Refactorizar antes de automatizar con AI significa hacer explícitas estas fronteras:

• Entidades nombradas con definición única. Si "cliente" significa tres cosas en tres lugares, el agente no puede determinar cuál aplica. Un refactor que introduce CuentaFacturacion, UsuarioFinal y MiembroOrganizacion le da al agente — y al equipo — un vocabulario inequívoco.
• Máquinas de estado explícitas. Si un ticket puede estar "abierto," "pendiente," "escalado," o "resuelto" pero las transiciones válidas no están documentadas, el agente intentará transiciones inválidas. Un refactor que codifica la máquina de estados como restricción hace imposible las transiciones inválidas, sea quien sea — o lo que sea — que las dispare.
• Fronteras de ownership en el código. Si cambiar un módulo afecta silenciosamente a otro, el agente no puede delimitar sus cambios de forma segura. El radio de explosión del agentic coding se amplifica cuando las fronteras de módulo no son enforced por el build system.
• Invariantes documentados. Si el sistema de facturación nunca debe generar una factura negativa pero esta regla solo vive en la memoria de un ingeniero senior, el agente eventualmente generará una factura negativa. Una restricción codificada como regla de validación, test o schema check lo previene sin importar quién — o qué — dispare la operación.

Los workflows desordenados crean uso impredecible de herramientas

Los agentes de AI no solo leen código. Ejecutan herramientas: llamadas a APIs, consultas a bases de datos, operaciones de archivos, notificaciones. La secuencia de uso de herramientas depende de la comprensión que el agente tiene del workflow. Cuando el workflow es ambiguo, la secuencia se vuelve impredecible.

Consideremos un workflow de reembolso donde la documentación dice "reembolsar al cliente y notificarlo" pero el proceso real involucra verificar señales de fraude, validar que el método de pago sigue activo, calcular montos parciales según uso, y registrar un evento de auditoría. Un agente operando desde el workflow documentado se salta cuatro pasos críticos. Un agente operando desde el código real — si el código es limpio — ejecuta todos.

La brecha entre workflows documentados y comportamiento real es donde viven los fallos de automatización. Refactorizar cierra esta brecha:

• Reemplazando secuencias implícitas con orquestación explícita (una máquina de estados, un pipeline, o una coreografía).
• Extrayendo side effects de la lógica de negocio para que el agente pueda componerlos en vez de adivinarlos.
• Haciendo visibles los modos de fallo: ¿qué pasa cuando la verificación de método de pago falla? El workflow refactorizado tiene una rama explícita. El workflow desordenado tiene un try/catch que traga silenciosamente el error y continúa.

Refactoring no es limpieza — es infraestructura de automatización

El encuadre importa. Refactoring posicionado como "pagar deuda técnica" compite con feature work y pierde. Refactoring posicionado como "construir la superficie sobre la que operan los agentes de AI" es inversión en infraestructura con retorno medible: el agente funciona correctamente, o no.

El checklist de readiness para automatización:

• Nombres: cada entidad, estado y operación tiene un nombre canónico usado consistentemente en código, configuración y documentación.
• Estados: cada workflow tiene una máquina de estados explícita con transiciones válidas codificadas como restricciones, no como documentación.
• Ownership: cada módulo, servicio y workflow tiene un equipo dueño único. CODEOWNERS, ownership de schemas y asignación de runbooks están alineados.
• Tests: los paths críticos tienen characterization tests que anclan el comportamiento actual. El agente puede modificar código sin regresión silenciosa porque la suite de tests detecta drift comportamental.
• Rollback: cada acción automatizada tiene un camino de undo definido. Si el agente comete un error, el sistema puede recuperarse sin intervención manual.

Cada ítem de esta lista es un target de refactoring. Ninguno es opcional si el objetivo es automatización confiable. El impuesto de calidad que AI impone a codebases sin mantenimiento se acumula con cada cambio generado por agente que pasa tests pero viola la estructura.

La diferencia en la práctica es medible. Un equipo que invirtió dos semanas codificando la máquina de estados de su pipeline de deployment en etapas explícitas y nombradas antes de conectar un agente de AI reportó cero deployments mal enrutados en el primer mes. Un equipo que conectó un agente a un pipeline sin documentar pasó tres semanas debuggeando por qué builds de staging se estaban promoviendo a producción — el agente infirió la regla de promoción a partir de un patrón en el historial de git que casualmente correlacionaba con deploys pero era en realidad una coincidencia. El refactoring costó dos semanas. El debugging costó tres semanas más un incidente. La matemática favorece la preparación siempre.

¿Qué debería refactorizarse antes de agregar automatización con AI?

El alcance del refactoring depende de dónde operará el agente. No todo necesita ser perfecto — pero el dominio que el agente toca debe ser legible.

¿Qué áreas del código necesitan refactoring antes de automatización con AI?

Priorizar los paths que el agente ejecutará. Si el agente genera código en el módulo de facturación, el módulo de facturación necesita fronteras explícitas, interfaces tipadas y characterization tests. Si el agente enruta tickets de soporte, la lógica de escalación necesita existir como código — no como un mensaje de Slack de 2023. El alcance del refactoring se define por la superficie operacional del agente, no por un mandato global de "pagar toda la deuda."

¿Cómo convertir conocimiento tribal en restricciones ejecutables?

Cada regla que solo vive en la memoria de una persona es una regla que el agente violará. El proceso de conversión: entrevistar a los expertos del dominio, documentar la restricción en lenguaje simple, codificarla como regla de validación o test, y conectarla al path que el agente ejerce. Un glosario de dominio que define términos como "suscripción activa," "cliente churned," y "evento facturable" con criterios precisos y computables elimina la ambigüedad que causa mal comportamiento del agente.

¿Cuándo está el codebase listo para automatización segura con AI?

La readiness no es un estado binario. Un módulo está listo cuando: los nombres de entidades son inequívocos dentro del contexto del agente, las transiciones de estado son explícitas y enforced, los paths críticos tienen cobertura de tests que detecta regresión comportamental, y los modos de fallo tienen caminos de recuperación definidos. Si alguna de estas condiciones falta en el dominio donde el agente operará, el refactoring no está terminado.

Un test práctico: ¿puede un ingeniero nuevo — alguien que nunca vio este módulo — leer el código y predecir qué hará el agente en cada estado? Si la respuesta requiere conocimiento tribal, el módulo no está listo. El agente es permanentemente un ingeniero nuevo. Nunca construirá el contexto institucional que los humanos acumulan en meses. El código debe ser legible sin ese contexto, o el agente actuará con información incompleta y confianza total.

Una visión opuesta

Un argumento frecuente sostiene que AI es la mejor herramienta para refactorizar. Los agentes pueden generar characterization tests, proponer grafos de dependencia, sugerir extracciones de módulos y ejecutar transformaciones mecánicas más rápido que los humanos. Esperar a refactorizar antes de automatizar retrasa el valor que la automatización entrega — y en mercados competitivos, la velocidad importa más que la pureza estructural.

Este argumento es correcto sobre la utilidad de AI como herramienta de refactoring. Se equivoca sobre la secuencia. Un agente generando characterization tests para un módulo que no comprende produce tests que anclan el comportamiento incorrecto o pierden los invariantes que importan. Un agente proponiendo un grafo de dependencias sin conocimiento del ownership de negocio produce un mapa técnicamente preciso pero operacionalmente inútil. El juicio humano que determina qué refactorizar — cuáles definiciones están mal, cuáles fronteras son disputadas, cuáles estados son implícitos — debe preceder a la automatización que ejecuta el refactoring. AI acelera el trabajo mecánico. No puede reemplazar las decisiones de dominio que hacen significativo ese trabajo mecánico.

Lo que importa recordar

• Los agentes de AI amplifican la estructura — incluyendo la mala estructura. Un sistema desordenado automatizado es un sistema desordenado moviéndose a velocidad de máquina.
• Refactorizar antes de automatizar con AI es inversión en infraestructura, no limpieza. Construye la superficie sobre la que los agentes operan de forma segura.
• Entidades nombradas, máquinas de estado explícitas, fronteras de ownership enforced, characterization tests y paths de rollback definidos son los cinco prerrequisitos para automatización segura.
• El alcance del refactoring se define por la superficie operacional del agente, no por un mandato global de deuda técnica.
• El conocimiento tribal que solo vive en la memoria es una regla que el agente violará. Convertirlo en restricciones ejecutables antes de que el agente lo encuentre.
• AI puede acelerar el trabajo mecánico del refactoring, pero las decisiones de dominio sobre qué refactorizar deben venir de humanos primero.

Conclusión

Los equipos que extraen más valor de la automatización con AI no son los que tienen más agentes. Son aquellos cuyos sistemas eran lo suficientemente legibles para que los agentes operaran sin amplificar cada falla ambiental. El refactoring que hace un codebase navegable para un ingeniero nuevo es el mismo que lo hace seguro para un agente — nombres explícitos, dominios acotados, invariantes enforced, comportamiento testeable. La pregunta no es si refactorizar. Es si hacerlo antes de que el agente llegue, cuando el costo es un sprint planificado, o después, cuando el costo es un incidente a escala.