AGENTS.md: un solo archivo de contexto para todos tus agentes de código (Codex, Gemini, Claude)

Te pasaste una tarde escribiendo un CLAUDE.md limpio. Tu agente por fin dejó de adivinar tu stack y empezó a lanzar el comando de test correcto. Y entonces un compañero abre el mismo repo con Codex, tú pruebas Gemini CLI en una rama aparte, y nada de ese contexto tan currado se traslada. Cada herramienta quiere su propio archivo, en su propio sitio.

AGENTS.md es la respuesta a ese lío: un único archivo en Markdown plano, en la raíz de tu repo, que cualquier agente de código lee antes de tocar tu código.

Qué es AGENTS.md en realidad

Nada de magia. Es un archivo Markdown llamado AGENTS.md, normalmente en la raíz del repositorio, que un agente carga como instrucciones permanentes antes de ponerse a trabajar. Piénsalo como el README que escribes para tus compañeros de IA en vez de para los humanos: qué es el proyecto, cómo compilarlo y testearlo, las convenciones que hay que respetar y las trampas que hay que evitar.

Es una convención abierta, ya leída por Codex y por una lista creciente de herramientas de agentes, pensada explícitamente para ser portable entre ellas. Un archivo, muchos agentes, en lugar de un archivo a medida por herramienta.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Ahora mismo el panorama está dividido por herramienta:

• CLAUDE.md es lo que busca Claude Code.
• GEMINI.md es la convención de Gemini CLI.
• AGENTS.md es el estándar entre herramientas, leído por Codex y otras, diseñado para ser el neutral.

El contenido es casi idéntico en los tres: contexto del proyecto, comandos, convenciones. La única diferencia real es el nombre de archivo que cada herramienta lee por defecto. Por eso mismo duplicar las mismas reglas a mano en tres archivos es una batalla perdida (más abajo hablamos de cómo mantenerlos sincronizados).

Si trabajas sobre todo en Claude Code, nuestra guía de CLAUDE.md profundiza en la estructura específica de Claude. AGENTS.md es el hermano neutral, independiente del proveedor, de ese archivo.

Qué poner dentro

Mantenlo corto y con mucha señal. Un agente lo lee en cada tarea, así que cada línea compite por su atención. Lo esencial:

• El stack, en una frase. "Next.js 16, TypeScript, Prisma, MariaDB." Sin historia, sin marketing.
• Los comandos que importan. Cómo instalar, ejecutar, compilar, testear y pasar el linter. Comandos exactos: npm test, no "lanza los tests."
• Las convenciones. Nombres, organización de archivos, gestión de errores, los patrones que de verdad haces respetar en las revisiones.
• Un mapa de directorios. Dos líneas sobre dónde vive cada cosa, para que el agente deje de hacer grep a ciegas.
• Reglas de leer antes de tocar. "Lee docs/payments.md antes de modificar nada dentro de billing/." Este simple hábito evita muchos destrozos.
• Prohibiciones firmes. "Nunca crees una rama sin que te lo pidan." "Nada de rutas absolutas de la máquina en archivos commiteados."

Los errores que hacen que los agentes lo ignoren

Un archivo de contexto falla en silencio. El agente no lanza ningún error, simplemente se desvía. Las causas habituales:

1. Demasiado largo. Un archivo de 600 líneas entierra las cinco reglas que importan. Quita todo lo que el agente pueda deducir del propio código.
2. Contradicciones. "Escribe siempre tests" en una sección, "sáltate los tests para los prototipos" en otra. El agente elige una al azar.
3. Rutas atadas a la máquina. /Users/you/project/... en un archivo commiteado se rompe para todos tus compañeros, y para cualquier agente en cualquier otra máquina. Usa rutas relativas.
4. Comandos obsoletos. El comando de test cambió hace seis meses, el archivo no. Ahora el agente lanza lo que no es con total seguridad.
5. Sin prioridades. Todo es "importante," así que nada lo es. Pon lo innegociable primero y etiquétalo.
6. Volcado de documentación. Esto son instrucciones, no una wiki. Enlaza a tu documentación, no la pegues dentro.

Mantener un único contexto entre proveedores

Aquí viene la parte práctica que la mayoría de las guías se salta. Si tú, o tu equipo, ejecutáis más de un agente CLI, no quieres tres copias divergentes de las mismas reglas.

Dos enfoques limpios:

• Un archivo canónico, punteros finos. Mete todo en AGENTS.md y haz que CLAUDE.md y GEMINI.md sean archivos de una línea que digan "ver AGENTS.md," o crea enlaces simbólicos. Una única fuente de verdad, todas las herramientas alimentadas.
• Un archivo, compartido por convención. Si tus herramientas pueden apuntar a una ruta personalizada, dirígelas todas a AGENTS.md y borra el resto.

En ambos casos la regla es la misma: escribe el contexto una vez, no una vez por proveedor. Es además la única forma de que se mantenga correcto, porque un archivo único es el único archivo que la gente mantiene de verdad.

Cuando ejecutas varios agentes a la vez

Un AGENTS.md a nivel de repo responde a "qué es este proyecto." No responde a "quién es este agente." Cuando lanzas un agente Backend, un agente Frontend y un agente QA en paralelo sobre el mismo código, cada uno necesita el contexto compartido del proyecto más su propio rol.

Esa es la capa que AgentsRoom añade encima de tu AGENTS.md. Cada agente recibe un rol dedicado con su propio system prompt (DevOps, Frontend, Seguridad y más), para que el archivo compartido siga siendo ligero mientras cada agente sigue sabiendo cuál es su trabajo. Es independiente del proveedor por diseño, así que el mismo montaje hace correr Claude, Codex o Gemini codo con codo, y tus instrucciones reutilizables viven en una biblioteca de prompts en lugar de retecleadas en cada sesión.

Cuando llegues a ese punto, el método para ejecutar varios agentes en paralelo sin perder el hilo es la lectura que sigue de forma natural.

La conclusión

Escribe un solo AGENTS.md. Mantenlo corto, mantenlo al día, mantenlo portable. Apunta cada herramienta hacia él en vez de mantener un archivo por agente. Tu contexto deja de estar atado al CLI con el que empezaste por casualidad, y tus agentes, sean los que sean, parten todos de la misma página.

¿Quieres todos tus agentes en una sola pantalla, cada uno con su rol y tu contexto compartido? Descarga AgentsRoom, conecta tu proveedor y pon tu flota a trabajar.