AGENTS.md: un solo archivo para todos tus agentes de IA

AGENTS.md es un archivo de texto en la raíz del repositorio con las instrucciones que leen los agentes de IA al trabajar en tu proyecto.

Claude Code, Codex, Cursor, Gemini CLI y GitHub Copilot lo leen de forma nativa. Eso significa que dejas de mantener las mismas reglas duplicadas en CLAUDE.md, en .cursorrules y en el prompt que pegas a mano cada semana. Este es el formato que la especificación abierta agents.md propone como punto común entre herramientas.

Qué es AGENTS.md y para qué sirve

Es un archivo Markdown versionado en el repositorio, en la raíz. Contiene lo que el agente necesita saber y que no puede deducir del código: comandos de compilación, convenciones, límites, formato de commits, qué módulos no se tocan.

Desde la versión 2.1.277, Claude Code lee AGENTS.md directamente. La documentación oficial de memoria de Claude Code lo describe así: un repositorio configurado para otros agentes de IA funciona sin necesidad de agregar un CLAUDE.md, un import o un ajuste.

Lo que el agente gana es contexto persistente entre sesiones. En la práctica eso se traduce en tres cosas concretas: menos correcciones repetidas, menos PR que rompen convenciones del equipo y menos tiempo de teammates nuevos explicando lo mismo.

La precedencia: qué archivo gana de verdad

Antes de escribir nada hay que entender qué pasa cuando hay más de un archivo. El orden por defecto es el siguiente:

1. Si existe CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md en el directorio de trabajo o en cualquiera de sus directorios padre, solo se leen esos. AGENTS.md queda ignorado.
2. Si no existe ninguno de los tres, entonces sí se lee AGENTS.md.
3. Siempre se cargan también las instrucciones gestionadas por la organización, que un proyecto no puede sobrescribir.

Ese punto uno es el que más confunde. Muchos migran desde CLAUDE.md, agregan un AGENTS.md, asumen que quedó activo y descubren días después que sus reglas de PHPUnit nunca se aplicaron. Detalle importante: ~/.claude/CLAUDE.md (tus preferencias personales) y .claude/rules/ no cuentan para esta decisión, así que siguen cargándose junto al AGENTS.md.

Los cuatro valores de Project instructions

Para cambiar ese comportamiento existe la opción Project instructions en /config, con cuatro valores:

• claude-md-or-agents-md (por defecto): lee los archivos de Claude si existen; si no, cae a AGENTS.md.
• claude-md-and-agents-md: lee los dos, con lo que declaran ambos.
• claude-md: solo los archivos de Claude, AGENTS.md se ignora.
• managed-only: descarta todo lo del proyecto y se queda con las instrucciones gestionadas por la organización.

Si vas en serio con el formato abierto, lo razonable es poner claude-md-and-agents-md y dejar CLAUDE.md como capa mínima mientras el equipo migra. El valor también se puede escribir a mano en ~/.claude/settings.json, en un archivo --settings o en la configuración gestionada; Claude Code lo ignora en los settings del proyecto:

{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}

Importar con @ y el detalle de Windows

La sintaxis de import es @AGENTS.md, y se resuelve recursivamente con un máximo de cuatro saltos. Funciona bien, con dos advertencias:

• Symlinks en Windows: crearlos requiere privilegios de administrador o el modo desarrollador, y Git los dejacheckout como un archivo de texto plano salvo que se habilite core.symlinks. En la práctica ese clon se queda con un CLAUDE.md de una línea. La documentación oficial recomienda el import @AGENTS.md en lugar del symlink si alguien del equipo trabaja en Windows.
• Algunas sesiones no lo cargan: en versiones anteriores a la 2.1.281, ciertas sesiones (por ejemplo en Amazon Bedrock o con telemetría deshabilitada) leen solo CLAUDE.md. Además, /config no muestra la opción si la sesión va justo después de actualizar. Verifica antes de asumir que tu AGENTS.md está activo.

En un proyecto PHP normal, la alternativa sana al symlink es un archivo real en la raíz y, si quieres compartir reglas entre repos, generarlo con una tarea de Composer o un script de Make.

Un AGENTS.md listo para Drupal 11 con Composer y Drush

Este es el punto donde la mayoría se queda en la teoría. Las reglas tienen que ser accionables: comandos que se copian, convenciones concretas, límites claros. Para un sitio en Drupal, drupal.org es la referencia para versiones de core y módulos; el resto son comandos de tu propio proyecto.

# AGENTS.md
## Contexto del proyecto
Sitio Drupal 11.1 con Composer 2, Drush 13 y PHPUnit 11.
Custom code en web/modules/custom. Ningún cambio en core ni en contributed.
## Comandos
- Instalar dependencias: `composer install`
- Actualizar a una versión nueva: `composer update --with-all-dependencies`
- Estado: `drush status`
- Cachés: `drush cr` o `drush cache:rebuild`
- Pruebas: `php vendor/bin/phpunit -c web/core/phpunit.xml.dist tests/src`
- Estilo de código: `php vendor/bin/phpcs --standard=phpcs.xml.dist web/modules/custom`
- Análisis estático: `php vendor/bin/phpstan analyse -c phpstan.neon`
## Convenciones
- Servicios en `*.services.yml`; nada de `hook_` para lógica de negocio nueva.
- Configuración en YAML exportada, nunca editada en la interfaz de administración.
- Namespaces de espacio `Drupal\mi_modulo\...`; clases y archivos en PascalCase.
- Variables en `snake_case`; métodos en `camelCase`.
- Sin `var_dump` ni `print` en código que llegue a revisión.
- Comentarios solo cuando explican un porqué, no qué hace la línea.
## Reglas de trabajo
- Nunca edites bajo `web/core/` ni `web/modules/contrib/`.
- Si un cambio requiere parche en un módulo contributed, el parche va en
`patches/` y se referencia desde `extra.patches` del `composer.json`.
- Antes de proponer un cambio de configuración, ejecuta `drush config:status` y reporta.
- Si agregas una dependencia de Composer, justifica en el PR por qué no basta
una función nativa o el core.
- Nada de `drush sql:query` con datos de producción; solo en staging.
- Si el cambio afecta rendimiento o seguridad, menciónalo explícitamente al final.
## Git
- Ramas: `feature/`, `fix/`, `chore/`. Nunca push directo a `main`.
- Mensajes de commit en imperativo, menos de 72 caracteres.
- No incluyas archivos de settings, ni dumps de base de datos, ni `.env`.

Tres cosas hacen que este tipo de archivo funcione: los comandos son copiables sin interpretar, los límites son verificables (web/core/ es innegable para todos) y cada regla responde a un error que se repite en el equipo.

Cómo verificar que tus instrucciones se están cargando

Un AGENTS.md mal escrito es peor que ninguno, porque genera confianza falsa. Estas son las formas de comprobarlo:

• /context muestra la lista bajo Memory files con todos los archivos de instrucciones que se cargaron en la sesión. Si AGENTS.md no aparece, la precedencia está mal o el archivo no está donde creés.
• La línea de arranque: en una sesión interactiva Claude Code muestra un mensaje como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. Es la confirmación más rápida.
• Prueba de humo: pídele al agente que ejecute una regla que solo exista en tu AGENTS.md, por ejemplo que corra drush cr después de tocar configuración. Si lo hace sin que se lo pidas, la instrucción se cargó.

# Confirmar que el archivo está en la raíz y es UTF-8
ls -la AGENTS.md
file AGENTS.md
git ls-files AGENTS.md

Si el proyecto tiene varios paquetes (un monorepo con sites/, modules/ y themes/), pon un AGENTS.md más corto en cada subdirectorio con las reglas específicas de esa parte, y deja el global solo con lo transversal. Claude Code carga el AGENTS.md de un subdirectorio cuando abre un archivo allí con la herramienta Read. El archivo de la raíz no tiene que repetir lo que un subdirectorio ya dice.

Un detalle que sorprende: AGENTS.local.md, AGENTS.override.md y todo lo que viva bajo un directorio .agents/ no se leen. Si necesitas un archivo personal en el proyecto, la ruta correcta sigue siendo CLAUDE.local.md.

El formato es abierto, pero la convención de contenido es tuya

AGENTS.md nació como una propuesta de OpenAI en agosto de 2025 y la Agentic AI Foundation, de la Linux Foundation, loDHAlectó como estándar abierto en diciembre de 2025. Hoy lo consumen Codex, Cursor, Gemini CLI, GitHub Copilot y otras herramientas de la especificación agents.md.

Eso significa dos cosas prácticas: es un formato estable y es un formato interoperable. No inventes campos propios, no agregues front matter, escribe Markdown legible. Reglas claras, secciones con encabezados, ejemplos de código reales.

Qué hacer si hoy tienes CLAUDE.md con dos años de reglas

No lo borres de un día para otro. La migración ordenada funciona así:

1. Mueve a AGENTS.md todo lo que sea regla del proyecto: comandos, convenciones, límites. Deja en CLAUDE.md solo preferencias personales de tu máquina o del equipo.
2. Pon claude-md-and-agents-md en /config durante unas semanas.
3. Corre /context una vez al día durante esa quincena y revisa que no haya duplicados ni contradicciones.
4. Cuando nadie nombre ya CLAUDE.md, bórralo o déjalo de tres líneas con un @AGENTS.md.

El orden importa: hacer esto bien cuesta una tarde y te ahorra meses de "mi agente no obedece". Si en tu pyme cada proyecto PHP, Drupal o e-commerce tiene reglas distintas, escribir ese AGENTS.md una vez y versionarlo es la inversión más barata de este trimestre. Si quieres, en Saibher te ayudamos a dejar el de tu proyecto Drupal bien armado y medido.

Preguntas frecuentes

¿Cuál es la diferencia entre CLAUDE.md y AGENTS.md?

AGENTS.md es un estándar abierto multipropiedad; CLAUDE.md es el formato propietario de Claude Code. Por defecto Claude Code lee CLAUDE.md y CLAUDE.local.md si existen, y solo cae a AGENTS.md cuando no encuentra los suyos. La diferencia práctica es que AGENTS.md funciona igual en Codex, Cursor, Gemini CLI y Copilot.

¿Puedo tener AGENTS.md en un proyecto que no es de IA?

Sí, y es justo el caso de uso. El archivo lo leen los agentes, no el proyecto. En un repositorio Drupal, WordPress o Node normal no agrega dependencias ni cambia el build: es un .md que describe convenciones que ya tenías en algún lado, solo que ahora todas las herramientas las leen.

¿AGENTS.md y CLAUDE.md se pueden usar al mismo tiempo?

Sí. Configura Project instructions en claude-md-and-agents-md y ambos se cargan, con los archivos de cada directorio primero y el AGENTS.md después. La alternativa más limpia a largo plazo es dejar solo AGENTS.md con las reglas del proyecto y usar CLAUDE.md para preferencias que no aplican a todo el equipo.

¿AGENTS.md funciona en Windows?

Sí como archivo. Lo que falla es el symlink: crearlo requiere privilegios de administrador o modo desarrollador, y si lo commiteas, Git lo deja como texto plano salvo que actives core.symlinks. Usa el import @AGENTS.md en un CLAUDE.md si alguien de tu equipo trabaja en Windows.

¿Cómo sé si mis instrucciones realmente se están aplicando?

Abre /context en Claude Code: ahí aparecen, bajo Memory files, las rutas de todos los archivos de instrucciones que se cargaron en la sesión. Si AGENTS.md no está en la lista, revisa la precedencia, es decir si existe un CLAUDE.md en la raíz, y vuelve a arrancar la sesión.