¿Cómo evitar que un agente de IA deje la base de código hecha un desastre?

Respuesta corta: el desorden que deja un agente de IA no está repartido por el proyecto, se concentra en un puñado de archivos que toda tarea tiene que tocar. Midiendo el repositorio de este sitio el 11 de agosto de 2026, 410 de los 641 archivos versionados aparecen en un único commit en toda su historia, mientras que tres archivos aparecen en 56 commits cada uno, más de dos veces y media el cuarto puesto. Vigilar esos pocos archivos rinde más que cualquier regla general de estilo. Este repositorio lo escriben agentes de IA en git worktrees paralelos, y eso lo sabemos por operar el proyecto, no por haberlo deducido del git.

¿Por qué el código escrito por IA parece limpio archivo a archivo y aun así se pudre?

Porque la unidad de trabajo de un agente de IA es la tarea, y la unidad de calidad de una base de código es el conjunto. Cada entrega sale internamente coherente: nombres consistentes, prueba presente, formato impecable. El defecto no vive dentro de la entrega, vive entre entregas. El agente que resuelve la tarea de hoy no sabe qué inventó el agente del martes, así que escribe una función que ya existía con otro nombre, una segunda forma de formatear fechas, una tercera convención para manejar errores. Ninguna de esas decisiones está mal por separado, y justo por eso pasan. La pregunta apareció con esas palabras en r/ClaudeAI el 5 de agosto de 2026, en el título "How are people using Claude Code without letting it make the codebase messy?". El mismo día, r/ExperiencedDevs discutía un problema vecino y no idéntico, "What do you do when a developer submits AI generated code they clearly don't understand?": ahí el tema es quién responde por el código, no la acumulación. Nuestra lectura es que ambas conversaciones parten del mismo sitio, que la salida del agente resulta aceptable pieza a pieza.

¿Dónde se acumula el desorden en realidad?

En los archivos compartidos, y la concentración es más marcada de lo que sugiere la intuición. El repositorio de este sitio tiene 324 commits entre el 18 de julio y el 10 de agosto de 2026, con 641 archivos versionados. Contando con el comando de la sección siguiente, 410 de esos archivos aparecen en un único commit y nunca recibieron un segundo. En el otro extremo, los tres catálogos de traducción del sitio, uno por idioma, aparecen en 56 commits cada uno, y el cuarto archivo más editado del proyecto aparece en 22. La caída del trío de la cima al cuarto puesto, de 34 commits, es mayor que la distancia entre el cuarto puesto y el suelo, que es todo el resto del proyecto. Eso desplaza el problema: una regla general de estilo actúa sobre un proyecto en el que cerca de dos tercios de los archivos nunca se volvieron a abrir. El desgaste está en la minoría que toda tarea tiene que abrir.

¿Cómo descubrir cuáles son los archivos compartidos de tu proyecto?

Con un solo comando, y es el mismo que produjo los números de arriba. Ejecuta git log --name-only --format='' | grep -v '^$' | sort | uniq -c | sort -rn | head -10 y lee la lista de arriba abajo: son los archivos que más commits tocaron. En nuestros números, la cima la ocuparon los tres catálogos de traducción, el archivo de configuración de entorno y el de rutas, seguidos de un trío empatado en 18 commits formado por el layout del área interna, el proveedor de servicios de la aplicación y la página de inicio. Dos salvedades de lectura. La primera es de método: ese comando no ve lo que entró por commits de merge, así que subcuenta en un repositorio que integra fusionando, y en el nuestro, contando también los merges, los tres catálogos pasan de 56 a 59 commits, las nueve primeras posiciones siguen siendo las mismas y solo la décima cambia de archivo. Lo que cambia de verdad no es el orden, es el empate, porque el trío de 18 pasa a 19, 19 y 18 y se deshace. La segunda es de apariencia: con la configuración por defecto de git, una ruta con un carácter fuera del ASCII sale escapada, y la línea muestra códigos numéricos en lugar del nombre. Es razonable esperar que un proyecto sin internacionalización tenga otro campeón, y por eso la lista se ejecuta en tu propio repositorio antes de escribir cualquier regla para tus agentes: es la que dice dónde tiene que aplicarse tu regla.

¿Qué hacer con el archivo compartido, en concreto?

Tres medidas que atacan al archivo compartido y no al agente. La primera es darle un orden interno explícito, declarado en la cabecera del propio archivo, alfabético o por secciones, porque un agente de IA respeta la convención que puede leer ahí mismo e ignora la convención que vive en la cabeza del equipo. La segunda es hacer que una inconsistencia rompa algo: una prueba que recorre los tres catálogos de idioma y falla cuando una clave existe en uno y no en los otros vale más que cualquier instrucción en prosa, porque las instrucciones se olvidan y una prueba en rojo no. La tercera es aceptar que un archivo compartido es punto de conflicto cuando varios agentes trabajan en paralelo, y programar la integración para que dos agentes no lo tengan abierto a la vez. Ninguna de las tres exige que el agente mejore.

¿La revisión de código no debería detectar el código duplicado?

La revisión de código no lo detecta, y esa distinción es lo que vuelve difícil el problema. La revisión de código juzga una entrega: este cambio es correcto, hace lo que promete, hay una prueba que lo demuestra. Una función duplicada supera esa vara con holgura, porque es correcta. Lo que la revisión de entrega no ve es el efecto de la quincuagésima entrega aprobada sobre el conjunto, ya que nadie abre las cuarenta y nueve anteriores para comparar. Si tu problema es la entrega y no la acumulación, el orden correcto para revisar salida de agente es otro asunto, y lo tratamos en cómo revisar código escrito por varios agentes de IA. La acumulación pide una pasada periódica con otra pregunta, del tipo "¿esto ya existe en otro sitio?", hecha contra el proyecto entero y no contra el diff.

¿Un archivo de instrucciones y un linter resuelven el desorden?

Resuelven parte de él, y la comunidad converge en esa combinación: el 6 de agosto de 2026, r/ClaudeWorkflows publicó una guía titulada "[Workflow] Claude Code Workflow: Preventing Messy Code with CLAUDE.md, Subagents, Linters, and TDD", que junta archivo de instrucciones, subagentes, linter y pruebas antes del código. La salvedad que conviene decir es que esas cuatro piezas atacan capas distintas. Linter y formateador resuelven la divergencia mecánica, que es la más barata y la menos dañina. Un archivo de instrucciones en la raíz del proyecto, sea CLAUDE.md o AGENTS.md, resuelve lo que el agente puede leer antes de actuar. Ninguno de los dos ve que la función que el agente va a escribir ya existe con otro nombre tres carpetas más allá, porque eso no es una regla, es conocimiento del repositorio. Para esa parte, lo que a nosotros nos funcionó fue reducir la superficie donde cabe la duplicación: archivo compartido ordenado, prueba de consistencia, y tareas más pequeñas, que producen entregas que sí puedes rechazar.

Lo que esta medición no demuestra

Un repositorio, 24 días, un producto. La concentración que medimos aquí puede ser efecto del tipo de proyecto, que es un sitio en tres idiomas y por eso tiene los catálogos de traducción como punto caliente obvio. Un proyecto sin internacionalización tendría otro campeón, y quizá una concentración menos extrema. Hay además un límite de método que conviene declarar: los 324 commits llevan todos el mismo autor de git, porque los agentes firman con la identidad de la persona que los ejecuta. El campo de autor no permite separar lo que escribió un agente de lo que se escribió a mano, y ese es un problema de trazabilidad que no resolvimos, solo medimos alrededor. Lo que la medición sostiene es la forma de la distribución, no el número exacto: la mayoría de los archivos nunca se revisita y una minoría diminuta absorbe el retrabajo.