AGENTS.md: qué es y qué archivo lee cada agente de IA
AGENTS.md es un archivo Markdown en la raíz de tu repositorio con instrucciones para agentes de código de IA: cómo se instala el proyecto, qué comandos corren los tests y qué convenciones seguir. Lo leen Cursor y Codex, y desde la versión 2.1.277 de Claude Code, publicada el 18 de septiembre de 2026, también Claude Code, aunque con una condición que conviene conocer.
Cada agente busca el archivo a su manera, así que abajo tienes qué lee cada uno según su documentación oficial, con qué prioridad y qué pasa cuando tienes varios. También verás cómo combinar AGENTS.md y CLAUDE.md para mantener una sola fuente, que es lo que ya hacen el esqueleto de Next.js y este mismo sitio.
- Qué es AGENTS.md
- Qué archivo lee cada agente
- Claude Code y AGENTS.md
- AGENTS.md o reglas de Cursor
- Un solo archivo para todos
- Cuánto debe medir
- Cuándo se queda viejo
- Qué crear en tu repo
Qué es AGENTS.md
AGENTS.md es un formato abierto, en Markdown normal y sin campos obligatorios, para darle contexto a un agente de código. Su web oficial lo define como "un README para agentes": un lugar fijo donde el agente encuentra lo que un compañero nuevo necesitaría saber para trabajar en tu proyecto.
La especificación vive en agentsmd/agents.md, con licencia MIT, y al escribir esto tiene más de 24.000 estrellas en GitHub. La web agents.md lista 24 herramientas compatibles, entre ellas Codex, Cursor, Jules, Aider, Gemini CLI, Zed, Devin y Junie.
Las secciones que sugiere la propia web son una descripción del proyecto, los comandos de build y test, el estilo de código, las instrucciones de testing y las consideraciones de seguridad. Un archivo mínimo se ve así:
# AGENTS.md
## Comandos
- Instalar dependencias: `pnpm install`
- Tests: `pnpm test`, que tiene que pasar antes de cada commit
## Convenciones
- TypeScript estricto, sin `any`
- Los componentes nuevos van en `app/components/`Dos reglas de la especificación ordenan los conflictos. Si hay varios AGENTS.md, gana el más cercano al archivo que se edita, y lo que le pidas al agente en el chat pesa más que cualquier archivo.
Qué archivo lee cada agente
Cursor y Codex leen AGENTS.md siempre, y Claude Code solo cuando no encuentra un CLAUDE.md. El resto de diferencias está en los archivos anidados y en cómo se combinan:
| Agente | Qué lee | Archivos anidados | Detalle |
|---|---|---|---|
| Cursor | AGENTS.md en la raíz y en subdirectorios, además de .cursor/rules |
Se combinan con los de directorios superiores; el más específico manda | Es su alternativa simple a las reglas .mdc |
| Claude Code | CLAUDE.md; AGENTS.md solo si no hay CLAUDE.md ni CLAUDE.local.md |
Lee el AGENTS.md de un subdirectorio al abrir un archivo de ahí, si ese subdirectorio no tiene CLAUDE.md |
Requiere la v2.1.277 o posterior |
| Codex | AGENTS.override.md o AGENTS.md, uno por directorio |
Concatena de la raíz del repo hasta tu directorio actual | Límite por defecto de 32 KiB en total |
| Gemini CLI | El archivo que configures en .gemini/settings.json |
Según su configuración | Se activa con "context": { "fileName": "AGENTS.md" } |
| Aider | Lo que indique .aider.conf.yml |
Según su configuración | Se activa con read: AGENTS.md |
Codex es el más detallado. Primero lee tu archivo global en ~/.codex y luego recorre el proyecto desde la raíz hasta el directorio donde lo lanzas, tomando en cada nivel AGENTS.override.md si existe y AGENTS.md si no.
El resultado se concatena en ese orden, así que el archivo más cercano a tu trabajo queda al final y pisa lo anterior. Deja de sumar archivos al llegar a project_doc_max_bytes, que por defecto son 32 KiB.
Claude Code ya lee AGENTS.md, si no hay un CLAUDE.md
Claude Code lee AGENTS.md como instrucciones del proyecto desde la versión 2.1.277, pero solo cuando no hay un CLAUDE.md en tu directorio de trabajo ni en los superiores. Su documentación lo resume en tres casos:
| Tu repositorio tiene | Claude lee |
|---|---|
Un AGENTS.md y ningún CLAUDE.md ni CLAUDE.local.md |
Tu AGENTS.md |
Un AGENTS.md y un CLAUDE.md o CLAUDE.local.md |
Solo tus CLAUDE.md |
Un CLAUDE.md que importa AGENTS.md |
Tu CLAUDE.md, con AGENTS.md incluido por el import |
La trampa está en CLAUDE.local.md. Si tu equipo trabaja con AGENTS.md y tú agregas un CLAUDE.local.md para tus notas personales, Claude deja de leer AGENTS.md en tus sesiones.
Para cambiar ese comportamiento, abre /config y ajusta Project instructions. El valor claude-md-and-agents-md carga los dos, primero el CLAUDE.md de cada directorio y después su AGENTS.md, sin leer dos veces uno que ya importaste.
Lo mismo se puede fijar en ~/.claude/settings.json. Claude Code ignora este ajuste en los settings del proyecto, así que no se comparte por el repositorio:
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}Hay sesiones donde la lectura directa no funciona. Pasa en versiones anteriores a la 2.1.277, si desactivaste el plugin integrado agents-md y a veces en la primera sesión después de actualizar; ahí Claude lee solo CLAUDE.md.
AGENTS.md o Cursor Rules: cuándo usar cada uno
AGENTS.md es la opción simple de Cursor y las reglas de .cursor/rules son la opción con control fino. La documentación de Cursor presenta AGENTS.md como "una alternativa simple a .cursor/rules": Markdown plano, sin metadatos.
Las reglas de proyecto son archivos .mdc con frontmatter (description, globs, alwaysApply), y ese frontmatter es lo que decide cuándo se aplican. Un .md normal dentro de .cursor/rules se ignora, porque le falta.
Si tus instrucciones valen para todo el repositorio y también las usa otro agente, AGENTS.md alcanza. Si necesitas que una regla solo se active con ciertos archivos, esa regla va en .mdc. Comparo las tres piezas de Cursor en Rules, AGENTS.md y SKILL.md en Cursor, y cómo escribir buenas reglas en la guía de reglas de Cursor.
Un solo AGENTS.md para todos tus agentes
La forma de mantener una sola fuente es escribir las instrucciones en AGENTS.md y dejar un CLAUDE.md que lo importe con @AGENTS.md. Así Cursor y Codex leen AGENTS.md, y Claude Code lo recibe por el import en cualquier sesión, incluidas aquellas donde la lectura directa no está disponible.
@AGENTS.md
## Solo para Claude Code
- Usa plan mode para cualquier cambio en `src/billing/`.Next.js 16.3.4 lo hace así de fábrica. Cuando next dev no encuentra ninguno de los dos archivos, escribe un AGENTS.md con sus reglas para agentes y un CLAUDE.md cuyo contenido es solo @AGENTS.md.
Este sitio funciona igual. El AGENTS.md lo mantiene Next.js (678 bytes) y mi CLAUDE.md empieza con @AGENTS.md y sigue con las reglas propias del proyecto, que ya suman unos 16 KB.
El esqueleto de Laravel lo resuelve peor. Desde su versión 13.10.1 trae un CLAUDE.md que le pide al agente, en palabras, que lea AGENTS.md.
La documentación de Claude Code avisa que así Claude solo ve AGENTS.md si decide abrirlo, y recomienda borrar ese CLAUDE.md o cambiar la frase por @AGENTS.md. Qué archivos quedan tras instalar Boost en un proyecto limpio está en la guía de Laravel Boost.
Cuánto debe medir un AGENTS.md
Un AGENTS.md debe medir lo justo para que quepa en cada sesión sin desplazar tu código, porque los agentes lo cargan entero al arrancar. Codex corta en 32 KiB por defecto, y como referencia, el AGENTS.md que genera Laravel Boost en un proyecto vacío ya ocupa 10.166 bytes, casi un tercio de ese límite.
Antes de agrandarlo, mide qué te cuesta. Cuando medí 30 días de mis transcripts de Claude Code para evaluar un plugin que prometía un 90% de ahorro, la parte que recortaba era el 0,366% de mi contexto; el método está en el artículo de shunt.
En un monorepo, la especificación propone un AGENTS.md por paquete en lugar de uno gigante en la raíz. Su web cuenta que, cuando la escribieron, el repositorio principal de OpenAI tenía 88.
Un AGENTS.md envejece con el código
Un AGENTS.md envejece cada vez que cambia un comando, una ruta o una convención y nadie actualiza el archivo. El agente lo sigue al pie de la letra, así que una instrucción vieja se vuelve un error repetido en cada sesión.
Construí driftwatch para encontrar esas partes en CLAUDE.md, AGENTS.md y skills. Lleva 341 documentos auditados en 66 repositorios públicos, con 37 hallazgos de los que 27 eran problemas reales; lo cuento en cómo uso Jev en driftwatch.
La especificación lo dice a su manera: trata AGENTS.md como documentación viva. Revísalo en el mismo PR que cambia lo que describe.
Qué archivo crear en tu repositorio
Si solo usas Claude Code, un CLAUDE.md te alcanza y no necesitas AGENTS.md. Si en el equipo conviven Cursor, Codex y Claude Code, escribe las instrucciones en AGENTS.md y agrega un CLAUDE.md con @AGENTS.md y lo específico de Claude debajo.
Empieza por lo que un agente no puede deducir del código: los comandos exactos de test y lint, las carpetas donde va cada cosa y las reglas que ya te costaron un error. Qué poner y qué dejar fuera lo cuento en qué poner en tu CLAUDE.md, y aplica igual a AGENTS.md.
Preguntas frecuentes
¿Claude Code lee AGENTS.md?
Sí, desde la versión 2.1.277. Lo lee como instrucciones del proyecto cuando no hay un CLAUDE.md ni un CLAUDE.local.md en tu directorio de trabajo o en los superiores. Si tienes un CLAUDE.md, lee solo ese, salvo que lo importe con @AGENTS.md o que cambies Project instructions en /config.
¿Qué diferencia hay entre AGENTS.md y CLAUDE.md?
AGENTS.md es un formato abierto que leen muchos agentes; CLAUDE.md es el archivo propio de Claude Code. CLAUDE.md admite más cosas de Claude, como que los hooks InstructionsLoaded se disparen. Para usar los dos sin duplicar, deja las instrucciones en AGENTS.md y un CLAUDE.md que lo importe.
¿Cursor lee AGENTS.md?
Sí. Cursor lo lee en la raíz del proyecto y en subdirectorios, y combina los anidados con los de directorios superiores, con prioridad para el más específico. Es su alternativa simple a las reglas .mdc de .cursor/rules.
¿Dónde va el archivo AGENTS.md?
En la raíz del repositorio. En monorepos puedes poner uno más dentro de cada paquete; el más cercano al archivo que se edita tiene prioridad. Codex además lee uno global en ~/.codex/AGENTS.md.
¿AGENTS.md reemplaza a .cursor/rules?
Para instrucciones generales del repositorio, sí. Si necesitas reglas que se activen solo con ciertos archivos (por globs) o que el agente cargue según su descripción, siguen haciendo falta los .mdc de .cursor/rules.
Fuentes
¿Tienes un proyecto en mente?
Trabajo con Laravel, WordPress, SEO técnico y servidores MCP. El primer paso es una llamada de descubrimiento, sin costo ni compromiso, donde me cuentas qué necesitas y te digo con honestidad si puedo ayudarte.