AGENTS.md: el archivo que casi todas las IA de código leen (y una no)

En el ecosistema actual del desarrollo de software, donde los asistentes de codificación basados en inteligencia artificial se han convertido en herramientas indispensables, surge un desafío recurrente: la dispersión de instrucciones. Cada plataforma —Copilot, Cursor, Cline, Devin Desktop, entre otras— exige su propio archivo de configuración, lo que genera una duplicación de reglas que rápidamente deriva en inconsistencias. Este fenómeno, conocido como instruction drift, es precisamente el problema que resuelve AGENTS.md, un estándar abierto que permite definir las reglas de un proyecto una sola vez y que la mayoría de las IA de código lo lean de forma automática.

AGENTS.md es un archivo de texto plano en formato Markdown ubicado en la raíz del repositorio. Sin sintaxis especial, sin frontmatter YAML, sin esquemas que aprender. Fue publicado por OpenAI en agosto de 2025 y cedido a la Linux Foundation para su gobernanza como estándar abierto. A mediados de 2026 ya se había adoptado en más de 60.000 repositorios de código abierto. Mientras que un README explica el proyecto a los humanos, AGENTS.md se lo explica a los agentes inteligentes.

Lo que pocos guías mencionan es que no todas las herramientas lo implementan de la misma manera. La mayoría —Copilot, Cursor, Devin Desktop, Aider, Kilo Code, Gemini CLI, Codex CLI y más de 30— lo leen nativamente desde la raíz del proyecto. La excepción honesta es Cline: su formato nativo es .clinerules/ y no detecta automáticamente el AGENTS.md del proyecto raíz; sí lee un archivo global, pero no el específico del repositorio. Conocer estas diferencias es clave antes de asumir que un único archivo cubre todas las herramientas.

Redactar un AGENTS.md eficaz requiere estructura y concisión. Las secciones imprescindibles incluyen: Comandos (instalar, ejecutar, testear, compilar), Convenciones (reglas específicas como “solo exportaciones con nombre, nunca por defecto”), Restricciones duras (usar la palabra “nunca” para dar peso), y añadidos avanzados como un Presupuesto de Contexto (indicar al agente cómo buscar antes de abrir archivos completos) y un Mapa de Enrutamiento Rápido que asocie tareas con archivos concretos, eliminando así alucinaciones de rutas. También puede incluir una Definición de Hecho con los comandos que deben ejecutarse antes de dar por terminada una tarea.

Un estudio realizado en febrero de 2026 por la ETH Zúrich (138 tareas reales de GitHub) reveló que los archivos de contexto escritos a mano ofrecen una mejora modesta del 4 % en el éxito de las tareas, mientras que los generados automáticamente tienden a empeorar los resultados. La conclusión es clara: hay que escribir el archivo manualmente, mantenerlo por debajo de 200 líneas y centrarse en información que el agente no pueda descubrir por sí mismo leyendo el código.

Una de las capacidades menos conocidas es el uso de archivos anidados: el AGENTS.md más cercano al archivo que se está editando tiene prioridad, permitiendo sobrescribir reglas globales para submódulos o paquetes legacy. OpenAI, por ejemplo, incluye 88 archivos AGENTS.md distribuidos en su repositorio Codex. Además, es importante tratar este archivo como público: no incluir secretos ni tokens reales, solo indicar dónde viven.

En Q2BSTUDIO somos expertos en desarrollo de aplicaciones a medida y software a medida, y sabemos que la integración de múltiples herramientas de inteligencia artificial requiere una gestión coherente de las instrucciones. Por eso ofrecemos servicios de consultoría en ia para empresas, ayudando a adoptar estándares como AGENTS.md para que sus equipos de desarrollo trabajen con agentes IA de forma eficiente. Además, combinamos estas capacidades con servicios cloud aws y azure para desplegar proyectos robustos, y con servicios inteligencia de negocio basados en power bi para convertir datos en decisiones. La ciberseguridad también es parte fundamental de nuestras soluciones, garantizando que cada archivo y cada pipeline esté protegido.

AGENTS.md no es solo un archivo más: es la llave para que los agentes de IA trabajen en armonía dentro de un proyecto, eliminando la deriva de instrucciones y liberando a los desarrolladores de tareas repetitivas. En Q2BSTUDIO te ayudamos a implementarlo correctamente y a sacar el máximo partido de la inteligencia artificial en tu organización.