AGENTS.md en Claude Code: un archivo para todos tus agentes
DominicodeEl CLAUDE.md del repositorio con el que opero Dominicode tiene una sola línea. Ocupa once bytes:
@AGENTS.md
Hasta el 26 de septiembre ese archivo tenía 191 líneas. Las moví todas a AGENTS.md, que abre con esta frase: «Instrucciones para cualquier agente de código (Claude Code, Codex, Cursor, Gemini…)». Hoy ese apaño sobra en muchos casos, porque AGENTS.md en Claude Code ya tiene soporte nativo. En muchos, no en todos, y ahí está lo interesante.
¿Por qué lo hice? Porque ese repo mueve más de 30 agentes y no quiero que sus reglas dependan de qué herramienta abra la terminal. Mantener dos archivos que dicen casi lo mismo es el problema: cambias una convención en uno, se te olvida el otro, y cada agente trabaja con una versión distinta de la verdad.
En corto: desde la v2.1.277, Claude Code lee AGENTS.md como instrucciones de proyecto cuando no hay ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo o por encima. Si existen los dos, por defecto manda CLAUDE.md, y lo cambias en /config → Project instructions. Mi recomendación: AGENTS.md para todo lo que sirve a cualquier agente y un CLAUDE.md solo si tienes algo que es de Claude y de nadie más.
¿Qué es AGENTS.md?
AGENTS.md es un archivo Markdown en la raíz del repositorio con las instrucciones que un agente de código necesita para trabajar en él —comandos de build y test, convenciones, estructura— escrito en un formato abierto que leen herramientas de distintos fabricantes.
La propia web de agents.md lo define como «un README para agentes». Lista más de veinte herramientas compatibles, entre ellas Codex, Jules, Cursor, Gemini CLI, Aider, Zed, Warp, Devin, Windsurf y el coding agent de GitHub Copilot. Hoy lo custodia la Agentic AI Foundation, bajo la Linux Foundation.
Un año pidiéndolo en un issue
Esto no llegó por sorpresa. El issue #6235 de anthropics/claude-code, «Feature Request: Support AGENTS.md», se abrió el 21 de agosto de 2025. Acumuló 409 comentarios y más de 5.000 pulgares arriba antes de cerrarse el 17 de agosto de 2026. La frase del autor resume el problema que yo tenía: CLAUDE.md «se siente demasiado específico de Claude Code» cuando colaboras con gente que usa otras herramientas.
Y el lanzamiento tuvo su propia polémica. En la v2.1.277 el soporte venía como un plugin interno que, según el issue #95690, dependía de un flag remoto: con la telemetría desactivada, o en Bedrock o Vertex, AGENTS.md no se cargaba. Sin error. Sin aviso. El issue sigue abierto a día de hoy.
Eso ya no es así. El changelog oficial de la v2.1.281 dice literalmente que el soporte pasa a funcionar también en Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways LLM y sesiones sin telemetría. Si alguien te dice que en Bedrock no funciona, te está contando la primera versión. Actualiza y listo.
La regla de precedencia de AGENTS.md en Claude Code
Por defecto gana CLAUDE.md: Claude Code solo lee AGENTS.md si no hay ningún CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo o por encima. La documentación de memoria de Claude Code lo resume en una tabla. Aquí va con la trampa que la doc esconde en una nota:
| Tu repo tiene | Claude Code lee (por defecto) |
|---|---|
AGENTS.md y ningún CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o por encima |
AGENTS.md |
AGENTS.md + CLAUDE.md |
Solo CLAUDE.md |
AGENTS.md + un CLAUDE.local.md personal (aunque no haya CLAUDE.md) |
Solo CLAUDE.local.md. AGENTS.md deja de cargarse |
CLAUDE.md con @AGENTS.md dentro |
CLAUDE.md con AGENTS.md importado, una sola vez |
La tercera fila es la que te va a morder. Creas un CLAUDE.local.md para tus URLs de sandbox y Claude olvida de golpe todas las convenciones del equipo.
Tu ~/.claude/CLAUDE.md, el gestionado por tu organización y .claude/rules/ no cuentan: se cargan junto a AGENTS.md.
Si quieres cambiar el comportamiento, /config → Project instructions acepta cuatro valores: claude-md-or-agents-md (el defecto), claude-md-and-agents-md (los dos, primero CLAUDE.md), claude-md y managed-only. Se puede fijar en ~/.claude/settings.json, pero Claude Code lo ignora en los settings de proyecto: no se lo puedes imponer al equipo desde el repo (sí desde managed settings).
Cómo migrar de CLAUDE.md a AGENTS.md según tu repo
No hay una migración. Hay cinco, según de dónde partes.
| Escenario | Qué hacer | Riesgo si no lo haces |
|---|---|---|
Solo CLAUDE.md |
Renómbralo a AGENTS.md. Saca a un CLAUDE.md nuevo lo que sea exclusivo de Claude y empiézalo con @AGENTS.md |
Codex, Cursor y compañía siguen sin ver tus convenciones |
Solo AGENTS.md |
Nada. Comprueba con claude --version que tienes 2.1.281 o superior |
Con una versión vieja o sin el plugin agents-md activo, Claude trabaja sin instrucciones |
| Los dos, con contenido distinto | Fusiona en AGENTS.md. Deja en CLAUDE.md solo @AGENTS.md y lo específico de Claude |
Por defecto Claude ignora AGENTS.md entero y los dos archivos divergen |
CLAUDE.md que dice «lee AGENTS.md» en texto |
Cámbialo por el import @AGENTS.md o bórralo |
Claude solo lo lee si decide abrirlo. Es una sugerencia, no una carga |
| Monorepo con archivos anidados | Un AGENTS.md por paquete y ningún CLAUDE.md en la ruta (ni en la raíz ni en los paquetes). Si quieres el CLAUDE.md con @AGENTS.md en la raíz, pon Project instructions en claude-md-and-agents-md |
Con un CLAUDE.md en la raíz y el valor por defecto, Claude no carga ningún AGENTS.md de paquete: el import solo trae el de la raíz |
En el monorepo, si no hay ningún CLAUDE.md en tu ruta, Claude Code carga al arrancar todos los AGENTS.md desde tu directorio de trabajo hacia arriba. El de un subdirectorio se carga cuando Claude lee un archivo ahí dentro, y solo si ese subdirectorio no tiene su propio CLAUDE.md. Es lo mismo que ya hacía con CLAUDE.md anidados, que expliqué en cómo funciona la memoria de CLAUDE.md en un flujo real. Ojo: con el CLAUDE.md de una línea en la raíz, esto deja de pasar salvo que cambies Project instructions a claude-md-and-agents-md.
¿Import o symlink? Prefiero el import: en Windows, Git sin core.symlinks saca el enlace como un archivo de texto de una línea. El import funciona en todas partes.
AGENTS.md vs CLAUDE.md: qué va en cada archivo
AGENTS.md |
CLAUDE.md |
|
|---|---|---|
| Quién lo lee | Claude Code (v2.1.277+), Codex, Cursor, Gemini CLI, Copilot y más de veinte herramientas | Solo Claude Code |
Imports con @ |
Claude los expande; el resto de agentes los lee como texto | Se expanden, hasta cuatro saltos |
Hook InstructionsLoaded |
No se dispara si Claude lo lee a través del ajuste | Se dispara |
--add-dir con CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 |
No se carga | Se carga |
| Limitación / riesgo | Un CLAUDE.md o CLAUDE.local.md en la ruta lo desactiva sin avisar |
Codex, Cursor y compañía no lo ven: tus convenciones existen para un solo agente |
Mi criterio es una pregunta: ¿esto le sirve a un agente que no es Claude?
Si la respuesta es sí, va a AGENTS.md. Comandos, estructura, convenciones de nombres, reglas de idioma, cómo se hacen los commits, qué no se toca. Es lo que antes metía en un CLAUDE.md para proyectos, solo que ahora lo leen todos.
Si la respuesta es no, se queda en CLAUDE.md, debajo del import. Algo así:
@AGENTS.md
## Solo Claude Code
- Skills del repo en `.claude/skills/`: usa `/dominicode-blog-post` para el pipeline del blog.
- Los guardarraíles viven en hooks (`.claude/settings.json`), no en este archivo.
- Usa plan mode para cualquier cambio en `tools/mailerlite/`.
Las skills, los hooks, los subagentes de .claude/agents/, el plan mode y los imports con @ son de Claude. Codex no sabe qué hacer con @docs/git.md: lo lee como texto. Si llenas AGENTS.md de imports, los demás agentes ven referencias rotas.
Plantilla mínima de AGENTS.md
Esta es la que uso para empezar cualquier repo nuevo. Cópiala y rellénala, no la amplíes hasta que un agente se equivoque dos veces en lo mismo:
# AGENTS.md
Instrucciones para cualquier agente de código que trabaje en este repositorio.
## Comandos
- Instalar: `bun install`
- Tests: `bun test`
- Lint y tipos: `bun run lint && bun run typecheck`
- Antes de dar una tarea por terminada, los tres en verde.
## Estructura
- `src/api/`: handlers HTTP. Nunca acceden a la base de datos directamente.
- `src/domain/`: lógica de negocio pura, sin imports de framework.
- `tests/`: espejo de `src/`.
## Convenciones
- Identificadores en inglés, textos visibles en castellano.
- Validación de entrada con Zod en el borde, nunca dentro del dominio.
- Commits en formato Conventional Commits.
## Límites
- No modifiques `migrations/` existentes: crea una nueva.
- No añadas dependencias sin justificarlo en la descripción del PR.
- Si una instrucción de este archivo choca con lo que te pide el usuario, pregunta.
Cero sintaxis propietaria. La doc de Claude recomienda no pasar de 200 líneas por archivo; el mío roza las 200 y ya pide una poda.
Escribir estas instrucciones como un contrato verificable, y no como una lista de deseos, es el tema del ebook gratuito sobre trabajar con agentes. El método completo, de la spec a las tareas que ejecuta el agente, está en el libro Spec-Driven Development.
Cuándo NO migrar a AGENTS.md
El soporte nativo no convierte AGENTS.md en un CLAUDE.md con otro nombre. Hay diferencias documentadas que importan.
Si dependes del hook InstructionsLoaded. Cuando Claude lee AGENTS.md a través del ajuste, ese hook no se dispara. Si lo usas para auditar qué instrucciones se cargan, mantén el CLAUDE.md con @AGENTS.md: con el import, el hook funciona como siempre.
Si trabajas con --add-dir. Con CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 se cargan los CLAUDE.md de los directorios añadidos, pero sus AGENTS.md no. En setups multi-repo, eso es perder instrucciones sin enterarte.
Si tu equipo tiene versiones de Claude Code desparejas. Por debajo de la 2.1.277 no hay soporte. En la primera sesión tras actualizar desde la 2.1.276 o anterior, a veces tampoco. Si no controlas las versiones, el CLAUDE.md con el import es un seguro que cuesta once bytes.
Si esperas que los agentes interpreten igual el archivo. Claude no lee AGENTS.override.md, AGENTS.local.md ni nada bajo .agents/. Y el estándar dice que «el más cercano tiene prioridad», mientras que Claude carga todos los AGENTS.md de tu ruta al arrancar, no solo el más cercano. Un mismo AGENTS.md no garantiza el mismo comportamiento en cinco herramientas.
Y lo que ninguna migración resuelve: AGENTS.md es contexto, no configuración. Si una regla no puede fallar nunca, no va en Markdown: va en un hook o en un test. Es la diferencia entre instrucciones y harness.
Qué haría yo hoy
Abre tu repo y ejecuta claude --version. Si estás en la 2.1.281 o superior, mueve el contenido de tu CLAUDE.md a AGENTS.md, deja en CLAUDE.md la línea @AGENTS.md y debajo solo lo que es de Claude. Luego abre una sesión nueva, lanza /context y comprueba que CLAUDE.md aparece en Memory files.
No borré mi CLAUDE.md de una línea, ni pienso hacerlo (en un monorepo con AGENTS.md por paquete, además, pon claude-md-and-agents-md): me cuesta once bytes y me cubre las versiones viejas, las sesiones sin el plugin y el día que alguien cree un CLAUDE.local.md sin avisar.
La decisión de fondo no es de formato. Es aceptar que tu repo lo van a tocar varios agentes y que las instrucciones son del repo, no de la herramienta. Si quieres ver ese flujo completo, de la spec al producto con Claude Code, está en el curso Construye con IA.
Preguntas frecuentes
¿AGENTS.md sustituye a CLAUDE.md en Claude Code?
No del todo. AGENTS.md en Claude Code funciona como instrucciones de proyecto solo cuando no existe ningún CLAUDE.md ni CLAUDE.local.md en la ruta. Lo que sirve a cualquier agente va en AGENTS.md; las skills, los hooks, el plan mode y los imports con @ siguen siendo cosa de CLAUDE.md, que puede importar AGENTS.md con una sola línea.
¿Desde qué versión lee Claude Code el archivo AGENTS.md?
Desde la v2.1.277, según el changelog oficial. En esa versión no funcionaba en Bedrock, Vertex, Foundry, gateways LLM ni con la telemetría desactivada. La v2.1.281 lo extendió a todos esos casos, así que la versión mínima razonable hoy es la 2.1.281.
¿Qué pasa si tengo AGENTS.md y CLAUDE.md a la vez?
Por defecto Claude Code lee solo CLAUDE.md e ignora AGENTS.md. Tienes dos salidas: añadir @AGENTS.md al principio de tu CLAUDE.md, o cambiar en /config el ajuste Project instructions a claude-md-and-agents-md. El import es la opción que funciona para todo el equipo sin que cada uno toque su configuración.
¿Tengo que borrar mi CLAUDE.md con @AGENTS.md ahora que hay soporte nativo?
No. El import nunca hace que AGENTS.md se lea dos veces. Bórralo solo si no contiene nada más y todo tu equipo está en la 2.1.281 o superior. Lo que sí debes quitar es un hook SessionStart que imprima AGENTS.md, porque ahora duplicaría el contexto.
¿Cómo sé si Claude Code ha cargado mi AGENTS.md?
Ejecuta /memory y busca la ruta del archivo en la lista. En sesiones interactivas también aparece una línea del tipo no CLAUDE.md found; AGENTS.md loaded al arrancar. Si no está, busca un CLAUDE.md o CLAUDE.local.md en tu directorio o por encima: es la causa más habitual.
¿Puedo usar imports con @ dentro de AGENTS.md?
Claude Code los expande igual que en CLAUDE.md. Pero no te lo recomiendo: el resto de agentes no entiende esa sintaxis y leerá @docs/git.md como texto literal. Si necesitas imports, ponlos en CLAUDE.md, que solo lee Claude. Hay además una diferencia de seguridad: en un AGENTS.md leído directamente, los imports externos al proyecto se cargan sin pedir aprobación, mientras que en CLAUDE.md Claude Code te la pide.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.