AGENTS.md es un formato abierto y estandarizado desarrollado por OpenAI para guiar a agentes inteligentes en proyectos de programación.

Este archivo, ubicado en la raíz de un repositorio, actúa como un “README para agentes”, proporcionando instrucciones claras sobre el entorno, pruebas, flujos de trabajo y normas de colaboración. Su adopción está creciendo rápidamente en la comunidad técnica global, facilitando la interacción entre desarrolladores y agentes de IA como Codex, GitHub Copilot y herramientas de automatización. Descubre cómo implementarlo y aprovechar sus ventajas en proyectos locales y en línea.

¿Qué es AGENTS.md y por qué es relevante en 2025?

AGENTS.md es un archivo en formato markdown que centraliza la información necesaria para que agentes de inteligencia artificial comprendan y ejecuten tareas en un repositorio de código. Su objetivo es estandarizar la comunicación entre humanos y agentes, reduciendo errores y optimizando procesos. Según OpenAI, más de 3,200 repositorios ya lo han integrado, reflejando su fuerte aceptación comunitaria y su capacidad para ahorrar hasta un 60% del tiempo dedicado a explicar configuraciones básicas en proyectos colaborativos.

Este formato es especialmente útil para:

• Equipos que buscan automatizar flujos de trabajo con agentes de IA.
• Desarrolladores que desean documentar comandos, pruebas y convenciones de código en un solo lugar.
• Proyectos que requieren integración con herramientas de CI/CD o asistentes como Codex o GitHub Copilot.

Estructura base y ejemplos prácticos

Un archivo AGENTS.md efectivo debe incluir secciones claras y concisas. A continuación, un ejemplo mínimo y sus componentes esenciales:

# AGENTS.md

## Consejos sobre el entorno de desarrollo
Ejecuta pnpm install para instalar dependencias. Usa pnpm test para correr pruebas. Usa pnpm lint antes de cada commit. ## Instrucciones de pruebas Las pruebas residen en /tests. Corrige cualquier error de tipo antes de hacer merge. ## Protocolo de pull requests - Título: [nombre_del_paquete] - Descripción breve - Ejecuta pruebas y linters antes de solicitar revisión.

En proyectos avanzados, se pueden agregar:

• Validaciones de seguridad y revisión automática de dependencias.
• Pasos para integraciones o despliegues continuos en servidores remotos.
• Reglas específicas para agentes como Codex o GitHub Copilot:refs[10-32].

Ventajas para desarrolladores novatos y expertos

Para usuarios sin experiencia, AGENTS.md elimina la curva de aprendizaje inicial: solo deben clonar el repositorio, leer el archivo y seguir los comandos indicados. Los expertos, en cambio, pueden personalizarlo para:

• Instruir a herramientas de orquestación de IA y testing automatizado.
• Definir rutas para hooks personalizados y flujos multiplataforma.
• Especificar comandos especializados por lenguaje o sistema operativo:

En repositorios públicos (como en GitHub), los agentes digitales detectan automáticamente este archivo para ejecutar flujos y validaciones, minimizando errores y asegurando la estandarización del ciclo de desarrollo.

Integración con agentes inteligentes: el caso de Codex

OpenAI lanzó en 2025 Codex, un agente de ingeniería de software que opera en entornos aislados en la nube y utiliza AGENTS.md para guiar sus acciones. Codex puede:

• Automatizar tareas como refactorización, escritura de pruebas y corrección de errores.
• Generar pull requests con cambios verificados y evidencia de terminal.
• Operar en contenedores seguros sin acceso a internet, garantizando la protección del código:refs[14-31,32].

Empresas como Cisco, Temporal y Superhuman ya lo utilizan para acelerar sus ciclos de desarrollo, demostrando su utilidad en entornos profesionales.

Problemas comunes y recomendaciones

Al implementar AGENTS.md, es importante:

• Evitar incluir datos sensibles como credenciales o llaves de acceso.
• Actualizar el archivo cada vez que cambien flujos de trabajo o normativas.
• Incluir secciones de solución de problemas frecuentes y enlaces a documentación actualizada.

Para migraciones en proyectos existentes, se recomienda una transición gradual y validaciones continuas para no interrumpir flujos previos.

Conclusión: el futuro de la colaboración con agentes

AGENTS.md no solo optimiza la interacción con agentes de IA, sino que también mejora la colaboración humana. Su adopción está transformando la forma en que equipos de desarrollo gestionan proyectos, desde startups hasta grandes corporaciones. Experimenta creando tu propio archivo y comparte tus adaptaciones en comunidades técnicas para enriquecer este estándar abierto.

¿Listo para implementar AGENTS.md en tu próximo proyecto? Consulta el repositorio oficial para ejemplos y recursos actualizados.