AGENTS.md: un solo archivo de contexto para todos tus agentes de código (Codex, Antigravity, 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 Antigravity 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

Cuando se escribió esta guía, cada herramienta buscaba su propio archivo. Desde entonces, la mayoría ha convergido en AGENTS.md:

• Codex lee AGENTS.md, igual que GitHub Copilot CLI, Cursor, Amp y la mayoría de los agentes CLI más recientes.
• Claude Code lee CLAUDE.md, y desde la versión 2.1.277 también lee AGENTS.md por su cuenta cuando tu directorio de trabajo y los directorios superiores no tienen CLAUDE.md ni CLAUDE.local.md. Cuando existe un CLAUDE.md, Claude solo lee ese archivo, salvo que cambies el ajuste Project instructions en /config.
• Antigravity CLI lee AGENTS.md o GEMINI.md, en la raíz del repositorio o en cualquier subdirectorio, además de una carpeta .agents/rules/ y reglas globales en ~/.gemini/.

El contenido es casi idéntico en los tres: contexto del proyecto, comandos, convenciones. Lo que sigue cambiando es qué archivo elige una herramienta cuando encuentra varios. 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). Comprobamos estos comportamientos el 10 de octubre de 2026 en la documentación de memoria de Claude Code y en la documentación de reglas de Antigravity.

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 solo AGENTS.md, nada más. Si nadie necesita reglas solo para Claude, quédate con un único AGENTS.md: Codex, Antigravity CLI y Claude Code 2.1.277 o posterior lo leen todos. La trampa es silenciosa: un CLAUDE.md, o un CLAUDE.local.md personal, añadido más tarde hace que Claude Code deje de leer AGENTS.md.
• Un archivo canónico, una importación. Mete todo en AGENTS.md y empieza CLAUDE.md con la línea @AGENTS.md, y luego escribe debajo las reglas solo para Claude. Claude lee primero el archivo importado. Nuestro propio repositorio funciona así: su CLAUDE.md es esa única línea. Un enlace simbólico (ln -s AGENTS.md CLAUDE.md) también funciona, pero mal en Windows, donde crear uno exige permisos de administrador o el Modo de desarrollador, y un clon sin core.symlinks recibe un archivo de texto de una línea en lugar de tus instrucciones.

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 Antigravity 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.

Preguntas frecuentes

¿Qué es AGENTS.md?

Un archivo Markdown, normalmente en la raíz de un repositorio, que los agentes de código cargan como instrucciones permanentes antes de trabajar: 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 compartida entre herramientas, no el archivo de una sola herramienta, y la leen Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp y, desde la versión 2.1.277, Claude Code.

¿Claude Code lee AGENTS.md?

Sí, desde Claude Code 2.1.277, pero solo cuando no hay ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo ni por encima de él. Entonces carga cada AGENTS.md desde el directorio de trabajo hacia arriba, y el AGENTS.md de un subdirectorio cuando abre un archivo allí. Si existe un CLAUDE.md, Claude solo lee ese archivo, salvo que pongas Project instructions en claude-md-and-agents-md dentro de /config. En versiones anteriores, pon la línea @AGENTS.md al principio de un CLAUDE.md.

¿Antigravity usa AGENTS.md o GEMINI.md?

Los dos. Antigravity lee un AGENTS.md, un GEMINI.md o una carpeta .agents/rules/ en la raíz del repositorio o en cualquier subdirectorio, y reglas globales desde ~/.gemini/. Las reglas se suman en lugar de reemplazarse, y cuando dos de ellas se contradicen, gana la regla del directorio más específico.

¿Me quedo con AGENTS.md o con CLAUDE.md?

Quédate con AGENTS.md como el único archivo que mantienes. Si además necesitas reglas solo para Claude, añade un CLAUDE.md cuya primera línea sea @AGENTS.md y escribe esas reglas debajo: Claude lee primero el archivo importado. Si no necesitas ninguna, AGENTS.md basta para Claude Code 2.1.277 o posterior. Evita dos copias completas de las mismas reglas: la que nadie edita se queda desactualizada.

¿Dónde va AGENTS.md?

En la raíz del repositorio para las reglas que valen en todas partes. Claude Code y Antigravity también leen los archivos AGENTS.md de los subdirectorios, así que un paquete o un servicio con sus propios comandos puede llevar su propio archivo, que se lee cuando el agente trabaja en esa carpeta.