Cada día aparecen nuevas herramientas basadas en inteligencia artificial para escribir, analizar y mantener código. Desde asistentes integrados en IDE como VS Code o Cursor, hasta agentes especializados como Devin, Aider o Gemini CLI. La promesa es clara: la IA puede actuar como un compañero programador capaz de instalar dependencias, ejecutar tests, corregir errores y realizar cambios complejos en un repositorio.
Pero surge un problema evidente: ¿cómo se explica a la inteligencia artificial la forma correcta de trabajar con un proyecto y sus convenciones? Durante años, la respuesta ha sido una mezcla desordenada de documentación dispersa, READMEs extensos, comandos enterrados en hilos de chat y procesos transmitidos oralmente dentro del equipo. El resultado: agentes que fallan, comandos incorrectos y tiempo perdido.
📌 Qué es AGENTS.md
AGENTS.md es un archivo en formato Markdown que se coloca en la raíz de un repositorio y que contiene instrucciones claras y específicas para que los agentes de IA puedan colaborar con un proyecto de software. Mientras que README.md está dirigido a personas, AGENTS.md está pensado para herramientas automáticas que necesitan ejecutar acciones.
Su intención es documentar aspectos como:
- Cómo instalar dependencias
- Qué comandos se deben usar para ejecutar el entorno de desarrollo
- Qué pruebas deben ejecutarse
- Qué estilo de código debe seguirse
- Qué reglas son obligatorias antes de realizar un commit o un pull request
🔍 Por qué no reemplaza al README
Los archivos README suelen tener múltiples objetivos: explicar el propósito del proyecto, describir su arquitectura general, incluir instrucciones para contribuir y ofrecer contexto histórico. Estas secciones son útiles para desarrolladores humanos, pero no para un agente automático.
Los agentes no necesitan una descripción detallada ni capturas de pantalla; necesitan comandos concretos y verificables. Un ejemplo sencillo:
- `pnpm dlx turbo run where <project_name>` para saltar rápidamente a un paquete sin explorar manualmente.
- `pnpm install --filter <project_name>` para que Vite, ESLint y TypeScript detecten el paquete.
- `pnpm create vite@latest <project_name> -- --template react-ts` para generar un nuevo paquete React + TS validado desde el inicio.
- Revisar el campo `name` en el package.json de cada paquete (ignorar el principal).Con eso, una herramienta puede configurar un entorno, iniciar un servidor y validar cambios.
📁 Lo que aporta en la práctica
La diferencia más importante es que los agentes modernos pueden ejecutar automáticamente los comandos descritos en AGENTS.md. Si el archivo indica, por ejemplo, que antes de realizar un commit hay que ejecutar ciertas pruebas, la IA intentará cumplir ese requisito y no considerará terminado el trabajo hasta que dichas pruebas finalicen correctamente.
Esto convierte a AGENTS.md en algo más que documentación; es una especie de contrato operativo entre el equipo y las herramientas inteligentes.
🧠 Un estándar ya adoptado
Aunque es un formato relativamente reciente, miles de proyectos ya utilizan AGENTS.md, incluidos repositorios públicos como Apache Airflow, Temporal Java SDK y varias bibliotecas de OpenAI. Es abierto y no depende de una compañía concreta, lo que favorece su adopción. Si se incorpora este archivo a un proyecto, muchos agentes de desarrollo reconocen su estructura y saben dónde buscar instrucciones de manera predeterminada.
🧾 Qué incluir en AGENTS.md
No existe una plantilla oficial, cada repositorio puede organizar el archivo como prefiera. Sin embargo, hay una serie de apartados que suelen resultar especialmente útiles para que un agente automático entienda el proyecto:
Estilo y convenciones
- Uso de TypeScript estricto
- Comillas simples
- Sin punto y coma
- Cada cambio debe ir acompañado de nuevas pruebas
Organización del proyecto
- Ubicación de paquetes
- Archivos que se deben ignorar
- Directorios con código de producción y de prueba separados
Buenas prácticas
- Formato de mensajes de commit
- Normas para abrir una pull request
- Consideraciones de seguridad
En resumen, la información que un nuevo miembro necesitaría para empezar, pero expresada de forma concisa y utilizable por una herramienta automática.
Ejemplo de estructura
# AGENTS.md
## Configuración del entorno
- `pnpm dlx turbo run where <project_name>` para saltar rápidamente a un paquete sin explorar manualmente.
- `pnpm install --filter <project_name>` para que Vite, ESLint y TypeScript detecten el paquete.
- `pnpm create vite@latest <project_name> -- --template react-ts` para generar un nuevo paquete React + TS validado desde el inicio.
- Revisar el campo `name` en el package.json de cada paquete (ignorar el principal).
## Pruebas
- Consultar el plan de CI en `.github/workflows`.
- `pnpm turbo run test --filter <project_name>` ejecuta todas las comprobaciones del paquete.
- Desde la raíz del paquete: `pnpm test` debe pasar antes de cualquier merge.
- Para centrarse en una prueba concreta: `pnpm vitest run -t "<nombre del test>"`.
- Tras mover archivos o modificar imports: `pnpm lint --filter <project_name>`.
- Añadir o actualizar tests con cada cambio.
## Reglas para PR
- Formato del título: `[<project_name>] <Título descriptivo>`.
- Antes de cualquier commit: ejecutar `pnpm lint` y `pnpm test`.
En definitiva, AGENTS.md debe contener toda la información esencial para arrancar, validar cambios y contribuir de forma consistente, pero expresada de manera breve, clara y fácil de ejecutar por una herramienta automatizada.
🗂️ Uso en monorepos
En monorepos con múltiples paquetes, se pueden establecer varios archivos AGENTS.md, uno por subproyecto. Los agentes leen siempre el archivo más cercano a los cambios que están realizando. Esto permite adaptar instrucciones a contextos distintos sin perder claridad.
/AGENTS.md
/packages/api/AGENTS.md
/packages/web/AGENTS.md
/packages/ui/AGENTS.md🧩 Conclusión
AGENTS.md es una herramienta sencilla para un problema real: proporcionar a los agentes de inteligencia artificial el contexto que necesitan para trabajar con un proyecto de software sin depender de la interpretación libre o de información incompleta. No requiere herramientas adicionales, no introduce un formato complejo y favorece la colaboración entre equipos humanos y entornos automatizados.
Fuente y referencias: Parte del contenido de este artículo está basado en la documentación publicada en https://agents.md/. Para ampliar información, ejemplos y recursos adicionales, puede consultarse el sitio oficial.
