Claude Code y AGENTS.md: cómo funcionan los archivos de instrucciones para agentes de IA en 2026

Qué es AGENTS.md y por qué existe

Durante un tiempo, cada herramienta de programación inventó su propio archivo de instrucciones. Cursor tenía .cursorrules, Claude Code tenía CLAUDE.md, Aider tenía .aider.conf.yml, Gemini tenía GEMINI.md, y así sucesivamente. Si anotabas tu repositorio para un agente, tenías que repetirlo todo para el siguiente.

AGENTS.md es la solución: un formato abierto para guiar a los agentes de programación, un único archivo en Markdown simple en la raíz del repositorio que leen muchos agentes. El proyecto lo llama un "README for agents", la descripción en una línea más clara que he visto. Tu README.md es para humanos (inicio rápido, guía de contribución); AGENTS.md contiene el contexto adicional que necesita un agente (pasos de compilación, pruebas, convenciones) y que saturaría un README.

No hay campos obligatorios. Es solo Markdown: usa los encabezados que quieras y el agente interpreta el texto. Surgió de una colaboración en todo el ecosistema, con OpenAI Codex, Amp, Jules de Google, Cursor y Factory, entre otros, y el primer commit llegó el 19 de agosto de 2025. Desde entonces se ha mudado a un hogar neutral y hoy lo administra la Agentic AI Foundation bajo la Linux Foundation, con el repositorio en agentsmd/agents.md bajo licencia MIT.

No es un experimento de nicho. El repositorio tiene 24,5k estrellas, una búsqueda de código en GitHub arroja más de 60k archivos de ejemplo, e incluso el propio repositorio de OpenAI contiene 88. Si lo habías descartado como puro bombo, este es el punto en el que yo dejaría de hacerlo.

Qué agentes lo leen de verdad

La página principal lista 24 herramientas compatibles, y la lista incluye buena parte de la categoría: Zed, OpenAI Codex, Gemini CLI, Cursor, Jules, Devin, Warp, Windsurf, VS Code, el agente de programación de GitHub Copilot, Aider, goose, Amp y más. Y desde este mes, también Claude Code. Cuando tantos proveedores competidores coinciden discretamente en el mismo archivo simple, el formato prácticamente ha ganado.

¿Claude Code lee AGENTS.md? Sí, ahora de forma nativa

Esta es la pregunta con la que llega la mayoría, así que va la respuesta directa: Claude Code lee AGENTS.md de forma nativa y requiere la v2.1.277 o posterior (lanzada el 18 de septiembre de 2026, cuando Anthropic adoptó la especificación multiherramienta). Un repositorio que otros agentes ya entienden funciona con Claude Code sin que añadas un CLAUDE.md, una línea de importación ni un ajuste.

El problema es qué ocurre cuando existen ambos archivos. El comportamiento por defecto:

Así que la trampa es un CLAUDE.md obsoleto que gana en silencio sobre un AGENTS.md bien mantenido. Si quieres ambos, el ajuste Project instructions (/config) tiene los valores claude-md-or-agents-md (el predeterminado), claude-md-and-agents-md (ambos, CLAUDE primero), claude-md (solo CLAUDE) y managed-only. Conviene saber que un CLAUDE.local.md también cuenta como archivo de la familia CLAUDE, así que añadir uno hace que Claude deje de leer el AGENTS.md hasta que cambies ese ajuste. Tu ~/.claude/CLAUDE.md, los archivos de política gestionada y .claude/rules/ no cuentan para la comprobación de "tiene un CLAUDE.md", así que siguen cargándose junto con AGENTS.md.

Una rareza más para tener en cuenta: un AGENTS.md leído directamente no aparece en /memory ni en /context, y los hooks InstructionsLoaded no se activan para él. Confirmas que se cargó por la línea AGENTS.md loaded al inicio de la sesión. Si eres nuevo en la herramienta, nuestra guía de inicio y la referencia de la CLI cubren lo básico.

CLAUDE.md vs AGENTS.md: la diferencia honesta

La gente lo plantea como una rivalidad. En realidad no lo es. AGENTS.md es el estándar multiherramienta; CLAUDE.md es el sistema de instrucciones más completo de Claude Code. Ambos son Markdown simple, y Claude ahora lee cualquiera de los dos.

La lectura práctica: si tu equipo usa una mezcla de agentes de programación, mantén la fuente de verdad en AGENTS.md. Si solo usas Claude Code y quieres importaciones o reglas por ruta, CLAUDE.md ofrece más mecanismos. Y puedes tener ambos si los conectas a propósito y no por accidente.

Conviene decirlo claro: CLAUDE.md no va a desaparecer y no es "peor". Tiene funciones que AGENTS.md deja fuera deliberadamente (la especificación se mantiene mínima a propósito). Elegir uno u otro depende de cuántas herramientas uses, no de cuál esté mejor construido.

Cómo carga Claude Code los archivos de instrucciones

Los archivos CLAUDE.md se cargan del ámbito más amplio al más específico, y todo lo descubierto se concatena en lugar de sobrescribirse, de modo que las instrucciones más cercanas al lugar donde lanzaste Claude se leen al final. Hay cuatro ámbitos:

1. Política gestionada (a nivel de organización, se carga primero, no se puede excluir). Está en rutas propias de cada sistema operativo, como /Library/Application Support/ClaudeCode/CLAUDE.md en macOS.
2. Usuario (~/.claude/CLAUDE.md), tus preferencias personales en todos los proyectos.
3. Proyecto (./CLAUDE.md o ./.claude/CLAUDE.md), compartido con el equipo mediante el control de versiones.
4. Local (./CLAUDE.local.md), tus notas privadas por proyecto que añades a .gitignore.

El descubrimiento es recursivo: Claude carga archivos CLAUDE.md de tu directorio de trabajo y de todos los directorios superiores. Los archivos en subdirectorios por debajo de ti no se cargan al iniciar; se incorporan bajo demanda cuando Claude lee archivos de esas carpetas. Ese comportamiento por subárboles es justo lo que mantiene los monorepos manejables, y refleja cómo funciona AGENTS.md: gana el archivo más cercano, y una instrucción explícita en el chat prevalece sobre todo. Para dar una idea de escala, el repositorio principal de OpenAI incluye 88 archivos AGENTS.md distintos, uno por paquete.

Esa división por paquete importa más de lo que parece, porque un único archivo en la raíz choca con un techo en una base de código grande. Es la queja más común que veo entre quienes usan estas herramientas a escala:

"AGENTS dot md files don't scale beyond modest codebases. Lots of discussions on this lately. If you're building serious software with Claude Code or any agentic tool, a single AGENTS dot md will eventually fail you."

elvis (@omarsar0), X

La solución no es un archivo más grande, sino más archivos: uno corto en la raíz y otro anidado en cada paquete, para que el agente siempre lea instrucciones acotadas a lo que está tocando.

Importaciones y el límite de 4 niveles

CLAUDE.md puede incorporar otros archivos con la sintaxis @path/to/import. Funcionan tanto rutas relativas como absolutas, los archivos importados pueden importar otros hasta una profundidad máxima de cuatro niveles, y envolver una ruta entre comillas invertidas evita que se importe (útil cuando solo quieres mencionar un archivo). Un detalle que sorprende a quien intenta reducir su contexto: dividir en importaciones no reduce el uso de tokens, porque los archivos importados se cargan igualmente al iniciar. Ayuda a organizar, no a reducir el tamaño.

Qué poner en un buen AGENTS.md (o CLAUDE.md)

No hay secciones obligatorias, pero las más habituales son la descripción del proyecto, los comandos de compilación y prueba, el estilo de código, las instrucciones de pruebas, las notas de seguridad y las reglas de PR o commits. El ejemplo canónico de la especificación se ve así:

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package.
- Run `pnpm install --filter <project_name>` to add a package to your workspace.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check.
- Fix any test or type errors until the whole suite is green.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

El detalle que lo convierte en algo más que documentación: los comandos de prueba que listas se ejecutan automáticamente. El agente intentará ejecutar las comprobaciones relevantes y corregir los fallos antes de terminar. Así que una línea precisa con pnpm test no es una nota, es una instrucción sobre la que el agente actúa.

En cuanto a la redacción, la guía de Anthropic para CLAUDE.md se aplica igual de bien a AGENTS.md, porque ambos se cargan en la ventana de contexto y se tratan como contexto, no como configuración impuesta:

• Que sea corto. Apunta a menos de 200 líneas; los archivos más largos consumen contexto y, según la documentación, en realidad reducen lo bien que el agente los sigue.
• Sé específico. Según la guía de redacción, "Use 2-space indentation" supera a "Format code properly"; "Run npm test before committing" supera a "Test your changes." Escribe reglas lo bastante concretas como para poder verificarlas.
• Estructúralo. Encabezados y viñetas en Markdown para agrupar instrucciones relacionadas.
• Mantén la coherencia. Si dos reglas se contradicen, Claude puede elegir una arbitrariamente, así que revisa los archivos anidados de vez en cuando.

Bien hecho, rinde más de lo que la mayoría espera. Como lo expresó un desarrollador en un hilo de Ask HN sobre cómo mantener estos archivos:

"AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes."

bisonbear, Hacker News

La forma más rápida de tener un primer borrador es /init, que analiza tu base de código en busca de comandos de compilación, pruebas y convenciones y escribe un archivo inicial (también puede migrar un archivo de Cursor o Copilot). Luego edítalo con /memory y confirma qué se cargó realmente con /context. Y como un CLAUDE.md se entrega como un mensaje de usuario después del prompt del sistema, no hay garantía de cumplimiento estricto; si necesitas que una regla se aplique pase lo que pase, la documentación recomienda un hook PreToolUse en lugar del archivo de instrucciones.

Cómo compartir un solo archivo entre todos los agentes

Si usas Claude Code junto con Codex, Cursor o Gemini, el objetivo es una única fuente de verdad. Con el soporte nativo, ahora es lo predeterminado: pon todo en AGENTS.md y no añadas un CLAUDE.md.

Si usas una versión anterior, o una configuración donde la lectura nativa no está disponible (Amazon Bedrock, otros proveedores externos o telemetría desactivada), la alternativa es importarlo desde un CLAUDE.md:

# CLAUDE.md
@AGENTS.md

También está el clásico enlace simbólico, aunque la documentación ya lo considera el último recurso:

ln -s AGENTS.md CLAUDE.md

La vía del enlace simbólico tiene inconvenientes reales: las herramientas Edit y Write de Claude se niegan a escribir a través del enlace (redirigen las ediciones al AGENTS.md de destino), y en Windows un enlace simbólico confirmado se descarga como texto plano salvo que core.symlinks esté activado. Por eso la importación es hoy la opción más limpia. El comando oficial de migración en una línea para consolidar un archivo antiguo es:

mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Errores comunes que conviene evitar

Algunas trampas que veo una y otra vez, la mayoría derivadas directamente de las reglas de precedencia:

• Un CLAUDE.md olvidado que anula en silencio tu AGENTS.md. Si existen ambos, Claude lee el CLAUDE.md. Borra el obsoleto o importa el otro.
• Tratar las importaciones como una dieta. Dividir un archivo enorme en importaciones con @ no reduce el contexto; todo se carga igualmente. Recorta el contenido en su lugar.
• Reglas vagas. "Write clean code" no sirve de nada. Da el comando exacto, la sangría exacta, el formato exacto del título del PR.
• Un archivo de 600 líneas. Pasadas las ~200 líneas, el seguimiento baja. Mueve los procedimientos de varios pasos a skills o subagentes, y las reglas para partes del código a archivos .claude/rules/ con alcance por ruta.
• Suponer que se aplica por la fuerza. Los archivos de instrucciones son contexto, no una barrera dura. Para un bloqueo real, recurre a un hook.

Para el entorno que rodea a tus archivos de instrucciones, merece la pena echar un vistazo a la guía de settings.json y a los permisos, ya que ambos influyen en cómo se aplican realmente las reglas.

Prueba eesel: la misma idea, para los agentes que atienden tu soporte

Aquí está el hilo conductor. AGENTS.md y CLAUDE.md son la forma de darle a un agente de programación sus instrucciones permanentes en un archivo. Ese agente de programación es infraestructura que configuras. eesel es la otra mitad del cuadro: en lugar de una herramienta a la que instruyes, es un compañero de equipo de IA listo para trabajar que contratas para un puesto definido, hoy un agente de helpdesk con IA que atiende tu cola de soporte y un redactor de blog con IA.

Y funciona con la misma filosofía de que "las instrucciones viven en un solo lugar". Las reglas permanentes de un agente de eesel no están dispersas en pantallas de ajustes; son un único conjunto de instrucciones editable, más tu conocimiento real (tickets anteriores, centro de ayuda, documentación). Es el modelo mental de AGENTS.md aplicado a un compañero de soporte.

Si ya vives en la terminal, esto te resultará familiar. eesel incluye una CLI (@eesel/cli) real, y su documentación es franca sobre la intención: todo lo que puedes hacer en el panel lo puedes hacer desde la terminal, incluso dejando que un agente de programación con IA haga la configuración. Puedes ejecutarla sin instalar (npx @eesel/cli init), chatear con el agente (eesel chat), editar sus reglas permanentes (eesel instructions) y ver lo que hizo (eesel activity). Cada comando imprime JSON y admite --dry-run, justo lo que permite que lo maneje un script o un agente en lugar de una persona haciendo clic.

Mejor aún, cada espacio de trabajo de eesel también es un servidor MCP. Ejecuta eesel mcp token y te imprime una línea lista para pegar de claude mcp add, de modo que Claude Code (o Cursor, o Codex) pueda gestionar las instrucciones de tu agente de soporte, revisar su actividad y aprobar acciones retenidas sin salir de tu editor. El mismo agente, tres superficies: terminal, scripts y agentes de programación mediante MCP.

El precio es una tarifa mensual fija desde $299/mes por 500 créditos (1 crédito por ticket o chat), las preguntas en el panel son en su mayoría gratuitas, y hay un plan gratuito con 100 créditos y sin tarjeta. Si ya escribes archivos AGENTS.md, te sentirás como en casa. Prueba eesel o apunta Claude Code hacia él y deja que haga la conexión.