El manual frente al reglamento: un malentendido costoso
El hecho de que muchos equipos malinterpreten el papel de un archivo AGENTS.md crea un costoso punto ciego operativo. Investigaciones recientes de ingenieros de Coldtea revelan una realidad cruda: solo el 27% de los 1,000 repositorios principales de GitHub poseen un archivo AGENTS.md, y una gran mayoría de estos se están utilizando incorrectamente. Este descuido generalizado deja una brecha crítica en la gestión de las contribuciones de IA.
El problema central radica en confundir un manual de operaciones con un 'reglamento'. La mayoría de los archivos AGENTS.md existentes funcionan como manuales, centrándose en descripciones de la arquitectura del proyecto o enumerando comandos exactos para compilar y probar. Le dicen a la IA cómo operar, pero, fundamentalmente, no logran restringir qué debe y qué no debe hacer.
Un verdadero AGENTS.md actúa como un reglamento, estableciendo barreras estrictas y restricciones negativas explícitas para los agentes de IA. Sin este reglamento, los agentes operan sin límites, lo que genera contribuciones inconsistentes, comportamientos inesperados y la introducción de posibles errores. Los repositorios más grandes, por ejemplo, dedican casi el doble de espacio a reglas de "no hacer", una señal clara de su comprensión de esta necesidad. La ausencia de directivas claras de "debe", "siempre" y "nunca" convierte una herramienta potencialmente poderosa en una responsabilidad impredecible.
El poder del 'no': lecciones de Vercel y Bun
La investigación de Coldtea revela un patrón crítico entre los repositorios líderes: los archivos AGENTS.md más efectivos priorizan las restricciones negativas explícitas. Los 100 repositorios principales dedican casi el doble de espacio a reglas sobre lo que no se debe hacer, en comparación con proyectos más pequeños, con 784 instancias de oraciones implícitas de "no hacer" encontradas.
Un sorprendente 90% de estos archivos de alto rendimiento aprovechan términos definitivos como 'debe', 'siempre' o 'nunca' para guiar a los agentes de IA. Esto no es accidental; es una estrategia deliberada para evitar acciones no deseadas y mantener la integridad del código, un sello distintivo de los sistemas robustos.
Ejemplos específicos subrayan esta precisión. El repositorio Next.js de Vercel, por ejemplo, prohíbe explícitamente los pies de página 'generado con Claude code' en las confirmaciones (commits). Este nivel de detalle garantiza que las contribuciones de la IA se alineen perfectamente con los estándares del proyecto y las expectativas humanas.
El repositorio de Bun ofrece otra ilustración poderosa con su advertencia en mayúsculas: 'NUNCA ejecutes bun test directamente: no incluirá tus cambios'. Tales prohibiciones directas eliminan la ambigüedad, evitando que los agentes ejecuten comandos perjudiciales que podrían comprometer el entorno de compilación o prueba.
Los límites explícitos son esenciales porque los agentes de IA operan sin contexto humano ni intuición. Carecen de la comprensión implícita del historial del proyecto, las normas del equipo o los posibles efectos secundarios. Por lo tanto, debes decirles con precisión qué archivos, funciones o patrones evitar meticulosamente, actuando como una barrera digital. Este enfoque proactivo evita errores sutiles y protege la base de código.
De 33 a 14,000 palabras: encontrar el tamaño adecuado para tu archivo
La gran variabilidad en la longitud del archivo AGENTS.md revela una mejor práctica incipiente. Considera los extremos: el archivo completo de VS Code abarca solo 33 palabras, actuando como una simple redirección. El de Neovim, apenas más largo con 35 palabras, se centra en una única regla de divulgación para las confirmaciones generadas por IA. Mientras tanto, el repositorio OpenHands presenta un formidable conjunto de instrucciones de 14,000 palabras. Este amplio espectro destaca el desafío de definir un modelo óptimo.
La investigación de Coldtea, sin embargo, ofrece una estrella polar práctica: una longitud mediana de aproximadamente 1,200 palabras. Esta cifra sugiere un punto óptimo pragmático para la mayoría de los proyectos, equilibrando el detalle suficiente para los colaboradores de IA con la claridad necesaria para la supervisión humana y la iteración rápida. Es un punto de referencia realista para establecer límites efectivos para los agentes sin una verbosidad abrumadora.
En última instancia, la complejidad de su archivo AGENTS.md debe alinearse directamente con la escala de su proyecto y los riesgos específicos que pretende mitigar con la asistencia de IA. Una utilidad más pequeña y enfocada podría necesitar barreras mínimas, pero un sistema complejo de múltiples colaboradores exige un reglamento sólido. Para obtener información más profunda sobre cómo los archivos de contexto realmente ayudan a los agentes de codificación, explore trabajos como Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?.
¿Te está gustando? Recibe uno así en tu bandeja cada mañana.
un correo al día · date de baja en dos clics · sin rastreadores de terceros
Su lista de verificación de 3 puntos para un repositorio a prueba de agentes
Después de analizar los 1,000 repositorios principales de GitHub, los ingenieros de Coldtea destilaron la esencia de los archivos AGENTS.md efectivos en una lista de verificación crucial de tres puntos. No se trata de sugerencias; se trata de proporcionar comandos precisos para sus agentes de IA, transformando su archivo en un reglamento sólido.
Para un repositorio a prueba de agentes, asegúrese de que su AGENTS.md incluya:
- Al menos una regla explícita de 'no hacer'. Esta directiva crítica, presente en el 86% de los archivos efectivos, establece límites claros para el comportamiento del agente. Sin estas restricciones negativas, los agentes a menudo recurren a suposiciones, lo que podría introducir cambios no deseados o pies de página "generados", como se vio con Next.js de Vercel. Esto incluye definir claramente lo que el agente nunca tiene permitido tocar.
- Detallar meticulosamente cómo deben formatearse los commits y pull requests. Presente en el 79% de los archivos exitosos, esto garantiza que el historial y los estándares del proyecto permanezcan consistentes, independientemente de si un humano o un agente de IA envía el código. El formato prescriptivo evita el caos en el sistema de control de versiones.
- Exactamente cómo ejecutar pruebas y linting de código. Aproximadamente tres cuartas partes (75%) de los archivos efectivos proporcionan estas instrucciones precisas. Estos no son pasos opcionales; son comandos directos para que el agente los ejecute, asegurando que cada contribución cumpla con los controles de calidad antes de la integración.
Preguntas frecuentes
¿Cuál es el error principal que cometen los proyectos con los archivos AGENTS.md?
El error más común es tratar AGENTS.md como un manual operativo (listando comandos) en lugar de un reglamento estricto que le dice a un agente de IA lo que debe y, más importante aún, lo que no debe hacer.
¿Cuáles son los elementos clave de un buen archivo AGENTS.md?
Un archivo efectivo incluye restricciones negativas explícitas (reglas de 'no hacer'), instrucciones claras para formatear commits y PRs, y pautas precisas sobre cómo ejecutar pruebas y linting del código.
¿Los proyectos grandes necesitan archivos AGENTS.md diferentes a los pequeños?
Sí. La investigación muestra que los proyectos más grandes y complejos tienen archivos AGENTS.md mucho más estrictos, dedicando casi el doble de espacio a las restricciones negativas (reglas de 'no hacer') para proteger la base de código.
¿Qué tan comunes son los archivos AGENTS.md en los principales repositorios de GitHub?
Todavía son relativamente raros. Un estudio de los 1,000 principales repositorios de GitHub encontró que solo el 27% tenía un archivo AGENTS.md, lo que indica una gran oportunidad de mejora en la orientación de los agentes de IA.