El análisis de 1.866 proyectos en GitHub revela brechas en las instrucciones para agentes de IA

Uno de cada tres proyectos populares en GitHub incluye ahora archivos de instrucciones específicos para agentes de codificación con IA, siendo AGENTS.md el formato estándar emergente. Un análisis reciente de 1.866 repositorios activos revela que, si bien la adopción es generalizada, especialmente en proyectos TypeScript, la calidad y la aplicabilidad de estas instrucciones varían significativamente.

Qué ocurrió

Los investigadores analizaron los repositorios con más estrellas en GitHub para comprender cómo los equipos están guiando a los asistentes de IA. Examinaron 1.866 proyectos que habían recibido commits en el año actual, buscando archivos como AGENTS.md, CLAUDE.md y otros diseñados para orientar el comportamiento del agente. El estudio encontró que 627 de estos proyectos, es decir, el 34%, incluyen al menos un archivo de instrucciones de este tipo.

Los datos muestran una clara preferencia por AGENTS.md, que aparece en el 78% de los proyectos que tienen alguna instrucción para agentes. CLAUDE.md también es común, presente en el 52% de esos proyectos, pero generalmente coexiste con AGENTS.md en lugar de reemplazarlo. Las tasas de adopción difieren notablemente según el lenguaje de programación. TypeScript lidera con el 73% de los proyectos que incluyen archivos de agentes, seguido por Go con el 58% y Rust con el 52%. En contraste, los proyectos en Perl rara vez los incluyen, con solo un 4% de adopción.

El estudio también destacó problemas relacionados con la longitud de los archivos y la redundancia. La mitad de los archivos principales de instrucciones superan las 100 líneas, con una mediana de 106 líneas. Aproximadamente 30 proyectos mantienen dos manuales de reglas separados, como un AGENTS.md y un CLAUDE.md con contenido diferente, lo que crea posibles conflictos para los agentes que utilizan distintas herramientas.

Cómo funciona

El análisis combinó scripts automatizados con juicios similares a los humanos proporcionados por un revisor de IA. Primero, un script recopiló datos sobre la existencia, longitud y encabezados de los archivos. Luego, un revisor de IA independiente clasificó muestras aleatorias de reglas para determinar si eran instrucciones genuinas y si podían ser aplicadas mediante código.

Los investigadores encontraron que tres de cada cinco reglas podían ser verificadas, al menos parcialmente, mediante un script, un linter o una prueba. Sin embargo, menos de una de cada veinte reglas nombra explícitamente la comprobación que las aplica. La mayoría de las reglas dependen de que el agente simplemente recuerde la instrucción, lo cual es menos fiable que la aplicación automatizada. Por ejemplo, una regla podría indicar "No usar patrones de desestructuración vacíos", algo que un linter podría detectar fácilmente, pero el archivo no especifica qué regla de linter se aplica.

El estudio también examinó la ubicación de estos archivos. Aunque muchos se encuentran en la raíz del repositorio, el 30% de los proyectos mantiene los archivos de instrucciones en subcarpetas. Esto permite que las reglas sean específicas para ciertas partes de la base de código, evitando que los agentes carguen contexto irrelevante cuando trabajan en otras áreas.

Detalles clave

• Tasa de adopción: El 34% de los proyectos activos populares tiene archivos de instrucciones para agentes, cifra que asciende al 73% en TypeScript.
• Longitud del archivo: El archivo principal mediano tiene 106 líneas, y el 52% supera las 100 líneas.
• Aplicabilidad: El 61% de las reglas podrían ser verificadas parcial o totalmente mediante un script, pero solo el 3,7% nombra la comprobación específica.
• Redundancia: Aproximadamente 30 proyectos mantienen archivos AGENTS.md y CLAUDE.md separados y no idénticos.
• Obsolescencia: Solo el 2% de los archivos hace referencia a rutas o scripts que ya no existen.
• Enfoque del contenido: El estilo de código, el comportamiento del agente y la corrección específica del proyecto son los temas más comunes, mientras que la seguridad y el rendimiento son raros.

Por qué importa

Para los equipos de ingeniería, estos datos resaltan una brecha entre escribir instrucciones y asegurar que se cumplan. Los archivos de instrucciones largos aumentan los costos de tokens y pueden diluir el enfoque del agente. El estudio de ETH Zurich citado en el artículo señala que, aunque los archivos escritos por desarrolladores ayudan marginalmente, pueden añadir hasta un 19% a los costos del agente. Mantener los archivos cortos y apuntar a documentación externa es más eficiente.

Más importante aún, depender de la memoria del agente para reglas críticas es riesgoso. Cuando una regla nombra su mecanismo de aplicación, como un linter específico o una comprobación de CI, crea una red de seguridad. Si el agente olvida la instrucción, la herramienta detecta el error. Sin este vínculo, los equipos dependen de la consistencia del agente, la cual se degrada a medida que se llenan las ventanas de contexto. La prevalencia de reglas no aplicadas sugiere que muchos equipos tratan estos archivos como listas de deseos en lugar de restricciones operativas.

Qué puedes hacer

• Auditar la longitud del archivo: Mantén tu AGENTS.md principal debajo de 100 líneas moviendo explicaciones detalladas a documentación enlazada.
• Nombra tus comprobaciones: Para cada regla, especifica el linter, prueba o script que la aplica, como "Aplicado por Sorbet/ForbidTMust".
• Verifica rutas: Comprueba regularmente que todos los comandos y rutas de archivo referenciados en tus instrucciones sigan existiendo.
• Consolida archivos: Si usas múltiples archivos de instrucciones, asegúrate de que los archivos secundarios apunten al principal para evitar reglas conflictivas.
• Prioriza reglas aplicables: Enfócate en reglas que puedan automatizarse y elimina aquellas que dependan únicamente de la memoria del agente, a menos que sean críticas.
• Usa reglas en subcarpetas: Coloca instrucciones específicas en subdirectorios para mantener el contexto relevante al código que se está editando.