¿El código limpio mejora a los agentes?

Si estás metiendo agentes de programación en tu flujo de trabajo, hay una pregunta que conviene hacer antes de comprar la promesa completa: ¿el estado del código base cambia de verdad lo que esos agentes pueden hacer? No hablamos solo de si el repositorio se ve bonito en una demo. Hablamos de si la limpieza del código, su organización y sus dependencias afectan tareas reales como corregir bugs, agregar funciones o navegar un proyecto grande sin romper medio sistema.

El paper “Does Code Cleanliness Affect Coding Agents?”, disponible en arXiv, entra justo en ese punto. Y eso importa porque muchas decisiones sobre adopción de IA en equipos de software parten de una suposición cómoda: si el agente es bueno, debería rendir igual en cualquier repositorio. El problema es que la realidad de un monorepo heredado, con módulos mal nombrados, tests frágiles y scripts dispersos, no se parece a un benchmark bien peinado.

Qué pregunta realmente el paper

La idea central del trabajo es simple, pero útil: medir si la calidad del código base influye en el desempeño de agentes de programación. No se queda en opiniones sobre “código bonito” o “código feo”. El foco está en tareas concretas donde un agente tiene que leer contexto, razonar sobre dependencias y producir cambios que pasen validación.

Eso cambia el debate. Porque en vez de preguntar si la IA “sirve” en abstracto, la pregunta pasa a ser: ¿sirve igual sobre un proyecto limpio que sobre uno desordenado? Para un equipo de producto, esa diferencia es enorme. Si el rendimiento cae cuando el repositorio está sucio, entonces la calidad del código no es solo un tema de mantenibilidad. También es una variable operativa para sacar provecho de la IA.

Qué significa “código limpio” en este contexto

En este tipo de estudios, “cleanliness” no suele significar una sola cosa. Normalmente combina señales como estructura de archivos, claridad de nombres, modularidad, documentación útil, tests disponibles y menor ruido en el historial o en la organización del proyecto. Es decir, no se trata de estética. Se trata de cuánta fricción encuentra un agente al entender qué hace cada parte.

Para ti, eso tiene una traducción directa. Si un agente tiene que tocar un módulo llamado utils.ts que hace 14 cosas distintas, y además depende de funciones con nombres genéricos, su margen de error sube. Si en cambio encuentra componentes bien separados, tests cercanos al código y puntos de entrada claros, la tarea se vuelve más mecánica.

Por qué esto importa más que un benchmark aislado

Muchos equipos evalúan agentes con tareas pequeñas o repositorios de juguete. Eso sirve para comparar modelos, pero no dice mucho sobre adopción real. En producción, la mayor parte del costo no está en escribir líneas nuevas, sino en entender código existente, respetar convenciones internas y no romper flujos colaterales.

Ahí aparece el valor del paper: te obliga a mirar el entorno, no solo el modelo. Un agente puede ser excelente generando código nuevo y aun así rendir peor en un proyecto caótico que en uno ordenado. Si ignoras eso, puedes terminar culpando al modelo cuando el problema está en la base de código.

Qué tipo de tareas sufren más

No todas las tareas se degradan igual cuando el código base está desordenado. Las más sensibles suelen ser las que exigen contexto transversal: seguir llamadas entre archivos, entender contratos implícitos, ubicar tests relacionados y editar sin romper dependencias ocultas. Ahí un agente no solo necesita “leer”, sino construir un mapa mental de cómo funciona el sistema.

En cambio, tareas muy localizadas, como cambiar un texto visible o ajustar una constante obvia, tienden a ser menos sensibles a la limpieza del repositorio. Eso no significa que el código sucio no afecte, pero el impacto es menor porque el espacio de decisión es más pequeño.

Señales prácticas de que el repositorio le complica la vida a un agente

Si quieres detectar rápido cuándo tu base de código está frenando a un agente, mira estas señales:

1. Archivos con demasiadas responsabilidades, por ejemplo un solo módulo con lógica de negocio, validación y acceso a datos.
2. Nombres genéricos en funciones y variables, como handleData, processItem o temp2.
3. Tests ausentes o desconectados del código que realmente falla.
4. Dependencias circulares que obligan a seguir varios archivos antes de entender una sola ruta.
5. Documentación desactualizada que contradice el comportamiento real.

Cuando esos patrones se acumulan, el agente pierde tiempo en exploración y aumenta la probabilidad de cambios incompletos. Y eso se traduce en más iteraciones humanas para corregir lo que la IA produjo.

Tareas donde sí conviene esperar una caída visible

Hay tareas donde la limpieza pesa más de lo que parece:

• Refactors que tocan varios módulos.
• Correcciones de bugs con causa raíz distribuida.
• Implementación de features que dependen de convenciones internas.
• Cambios donde hay que actualizar tests, mocks y fixtures al mismo tiempo.

En esas situaciones, un repositorio bien estructurado reduce el costo de navegación. Y ese costo no es abstracto. Se convierte en menos tokens desperdiciados, menos pasos de razonamiento fallidos y menos parches que luego hay que rehacer.

Lo que significa para equipos que adoptan IA

La lectura más útil del paper no es “la IA funciona” o “la IA no funciona”. La lectura útil es esta: si adoptas agentes de programación, la calidad del código base empieza a influir también en el retorno de esa inversión. No solo en mantenibilidad futura, sino en productividad inmediata.

Eso obliga a dejar de ver la limpieza de código como una tarea estética o de deuda técnica que se resuelve cuando haya tiempo. Si tu equipo quiere usar agentes para acelerar delivery, entonces la estructura del repo pasa a ser parte del stack productivo. Un código base más claro puede hacer que el mismo agente necesite menos correcciones humanas.

Qué cambia en el día a día del equipo

En un equipo que usa agentes de programación, la conversación deja de ser solo “¿qué modelo usamos?” y pasa a incluir “¿qué tan legible es nuestro sistema para una máquina que no conoce el contexto?”. Esa pregunta cambia prioridades de ingeniería.

Por ejemplo, si tienes dos iniciativas en paralelo, una para sumar un agente y otra para limpiar módulos críticos, el paper te da argumentos para no tratarlas como esfuerzos separados. Mejorar estructura, nombres y tests puede aumentar la efectividad del agente casi tanto como cambiar de modelo, dependiendo del caso.

Cómo leer esto si trabajas en LatAm

En LatAm, donde muchos equipos conviven con presión por entregar rápido, rotación de personal y bases heredadas, esto pega todavía más. La tentación suele ser usar IA para compensar deuda técnica. El problema es que la deuda técnica también puede reducir la utilidad de la IA.

Si estás en Ecuador, México, Colombia, Perú o Argentina, la recomendación práctica es parecida: no midas solo cuántas tareas resuelve el agente, mide también cuánto contexto consume para resolverlas y cuántas correcciones humanas necesita después. Ahí vas a ver si tu repo está ayudando o frenando la adopción.

Cómo evaluar tu propio repositorio sin adivinar

No necesitas un laboratorio académico para empezar. Puedes hacer una evaluación bastante honesta con un conjunto pequeño de tareas reales y una comparación entre partes limpias y partes desordenadas del mismo proyecto. La idea no es buscar perfección estadística, sino señales útiles para decidir dónde invertir.

Un enfoque razonable es tomar tickets de baja y media complejidad, correrlos con un agente y revisar tres cosas: tiempo hasta una primera propuesta útil, cantidad de cambios necesarios para que pase tests y número de archivos tocados para resolver el caso. Si el agente necesita demasiadas vueltas en zonas del repo con mala estructura, ya tienes un indicador.

Un protocolo simple de prueba

Puedes probar algo así:

1. Elige 5 tareas reales de mantenimiento o bugfix.
2. Divide el repo en zonas “ordenadas” y “desordenadas” según tu criterio de equipo.
3. Ejecuta el mismo agente sobre ambas zonas con el mismo prompt base.
4. Registra si la primera respuesta compila, si pasa tests y cuántas iteraciones requiere.
5. Compara el esfuerzo humano posterior, no solo la salida inicial.

Si quieres medir con algo más formal, también puedes usar métricas internas como porcentaje de tareas completadas sin intervención, tiempo medio de corrección y cantidad de archivos editados por tarea. No necesitas inventar una métrica perfecta para empezar a ver patrones.

Tabla de señales que puedes observar

Si tu equipo ya usa agentes, esta tabla te sirve como checklist de diagnóstico. Si todavía no los usas, también te sirve para preparar el terreno antes de escalar el experimento.

Qué deberías hacer con esta evidencia

La primera decisión útil no es comprar más herramientas. Es ordenar dónde usar IA y dónde no. Si el paper sugiere que la limpieza afecta el rendimiento, entonces conviene priorizar agentes en los repositorios o módulos donde la estructura ya ayuda. Ahí el retorno suele ser más rápido y la fricción menor.

Después, puedes usar el mismo hallazgo para justificar inversión en refactorización. No como un proyecto de “higiene” abstracta, sino como una mejora que también eleva la eficacia del asistente de programación. Esa narrativa suele funcionar mejor con producto y management porque conecta deuda técnica con velocidad de entrega.

Qué priorizar primero

Si quieres una ruta práctica, empieza por esto:

• Documenta los módulos críticos que más tocan los agentes.
• Agrega tests donde hoy el agente más falla.
• Reduce archivos monolíticos que mezclan lógica distinta.
• Renombra funciones y variables que no explican intención.
• Establece convenciones para prompts y revisiones humanas.

No hace falta limpiar todo el repo para ver beneficios. A veces basta con ordenar los puntos de entrada, los módulos más editados y las zonas donde más bugs aparecen.

Qué evitar

Evita usar agentes como excusa para congelar buenas prácticas. Si el equipo sabe que una parte del código está mal estructurada, no tiene sentido asumir que la IA la va a resolver sola. Tampoco conviene medir éxito solo por velocidad de generación, porque eso puede ocultar más trabajo de revisión y corrección.

También evita comparar resultados entre proyectos sin contexto. Un monorepo maduro con convenciones fuertes no se comporta igual que una app recién armada sobre deuda técnica acumulada. Si no separas esos escenarios, puedes sacar conclusiones falsas sobre el modelo cuando en realidad estás midiendo la base de código.

Tabla resumen

Si tu equipo quiere sacar provecho real de agentes de programación, el paper deja una idea bastante clara: el modelo importa, pero el repositorio también. Y en muchos casos, la diferencia entre una IA útil y una IA frustrante no está solo en el prompt, sino en cuánta disciplina tuvo tu base de código antes de que la IA llegara.

Para seguir profundizando, puedes revisar la ficha del paper en arXiv y la documentación oficial de herramientas que ya usas para evaluar automatización. Por ejemplo, la documentación de GitHub Copilot en https://docs.github.com/en/copilot y la de OpenAI en https://platform.openai.com/docs ayudan a entender capacidades y límites sin asumir magia donde no la hay.