Saltar al contenido principal

AGENTS.md e interoperabilidad entre herramientas

Intermedio

Ya conoces CLAUDE.md, el informe de proyecto de Claude Code. Pero tu repositorio probablemente lo toca más de un agente: un compañero usa Codex, CI usa un bot de programación, alguien abre el repo en Cursor. AGENTS.md es el estándar abierto que esas herramientas acuerdan leer, así que escribes las instrucciones de tu proyecto una sola vez en lugar de mantener un archivo distinto por cada herramienta.

What you'll learn
  • Qué es AGENTS.md y quién lo administra
  • Por qué Claude Code lee CLAUDE.md y no AGENTS.md
  • Tres formas fiables de mantener una única fuente de verdad entre herramientas
  • Cómo se fusionan los archivos AGENTS.md anidados y globales
  • Qué corresponde poner en el archivo y qué dejar fuera

Qué es AGENTS.md​

AGENTS.md es un archivo Markdown sencillo en la raíz de tu repositorio: piénsalo como un README escrito para agentes en lugar de personas. Le dice a un agente de programación cómo compilar, probar y contribuir al proyecto. El formato no tiene campos obligatorios: los agentes simplemente leen la prosa.

Es un estándar abierto administrado por la Agentic AI Foundation (AAIF), bajo la Linux Foundation, y a mediados de 2026 lo usan más de 60 000 proyectos de código abierto y lo leen más de 30 herramientas, incluyendo OpenAI Codex, Jules y Gemini CLI de Google, Cursor, Windsurf, Devin, Zed, Warp, Aider, goose, Amp y el agente de programación de GitHub Copilot.

What you'll learn
  • AGENTS.md es una convención, no un entorno de ejecución: cada herramienta decide cómo descubre, fusiona e inyecta el archivo.
  • No se impone ningún esquema: una prosa clara supera a una estructura rígida.
  • Complementa tu README; no lo reemplaza.

El detalle con Claude Code​

Aquí está la parte en la que la gente tropieza: Claude Code lee CLAUDE.md, no AGENTS.md. Si tu repositorio solo tiene un AGENTS.md, Claude Code lo ignora por defecto. No es un error: es anterior al estándar, pero significa que un repo con varias herramientas necesita una estrategia de sincronización deliberada, o tus instrucciones se desviarán silenciosamente entre sí.

Watch out
  • No asumas que Claude Code recurre a AGENTS.md: no lo lee automáticamente.
  • Dos archivos mantenidos a mano (CLAUDE.md y AGENTS.md) se desviarán. Elige una única fuente de verdad.
  • Verifica el comportamiento actual en la documentación oficial de memoria antes de confiar en cualquier afirmación de respaldo.

Mantén una única fuente de verdad​

Tres patrones mantienen CLAUDE.md y AGENTS.md sincronizados sin duplicar contenido. Elige según la plataforma de tu equipo.

Guided walkthrough1 of 3
  1. Haz que CLAUDE.md sea un enlace simbólico a AGENTS.md. Claude Code sigue los enlaces simbólicos y lee el destino byte por byte: un único archivo real, cero lógica de fusión. Salvedad: en Windows, crear un enlace simbólico requiere el Modo de desarrollador o permisos de administrador, así que los equipos multiplataforma pueden preferir el método de importación.

Enlaza CLAUDE.md al estándar compartido (macOS / Linux)

ln -s AGENTS.md CLAUDE.md

O mantén un CLAUDE.md de una línea que lo importe

@AGENTS.md
Pro tip
  • Usa el enlace simbólico cuando todo tu equipo esté en macOS/Linux: es lo que menos hay que mantener.
  • Usa @import cuando haya colaboradores en Windows.
  • Confirma con commit la opción que elijas para que todo el equipo obtenga el mismo comportamiento.

Cómo se fusionan los archivos anidados y globales​

Los agentes más completos tratan AGENTS.md de forma jerárquica, el mismo modelo mental que la jerarquía de memoria de CLAUDE.md. Codex, por ejemplo, recorre desde un archivo global en tu directorio personal hasta la raíz de Git y luego a tu carpeta actual, concatenando a medida que avanza:

Los archivos más cercanos al trabajo ganan, porque se concatenan al final y anulan la orientación anterior. Así, un services/payments/AGENTS.md hereda las instrucciones de la raíz del repo y añade reglas que solo se aplican dentro de ese servicio: coloca la orientación especializada lo más cerca posible del código especializado.

La interoperabilidad de un vistazo
Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.
1 / 5

Qué poner en él​

La misma disciplina que en un buen CLAUDE.md: el estándar solo sugiere unas pocas secciones comunes:

  • Resumen del proyecto — qué es esto, en dos frases.
  • Comandos de compilación y prueba — cómo ejecutar, probar y aplicar el linter.
  • Estilo de código — convenciones que un agente no puede inferir.
  • Instrucciones de prueba — qué significa "terminado".
  • Consideraciones de seguridad — qué no tocar ni confirmar nunca.
  • Pautas de commit / PR — formato de los mensajes, reglas de ramas.
Watch out
  • Los agentes siguen el archivo al pie de la letra: las instrucciones obsoletas o aspiracionales perjudican activamente, igual que con CLAUDE.md.
  • Mantenlo corto y veraz; describe cómo funciona el proyecto hoy.
  • Nunca confirmes secretos; haz referencia a documentos extensos en lugar de pegarlos.

Ponte a prueba​

Ponte a prueba

0/3
  1. ¿Lee Claude Code AGENTS.md automáticamente?
  2. Tu equipo está completamente en macOS y Linux. ¿Cuál es la forma de menor mantenimiento para compartir un único archivo de instrucciones entre Claude Code y Codex?
  3. Cuando los agentes fusionan un AGENTS.md global, uno de la raíz del repo y uno de un subdirectorio, ¿cuál gana en los conflictos?
Key takeaways
  • AGENTS.md es el estándar abierto, administrado por la Linux Foundation, que leen más de 30 agentes de programación: un README para agentes.
  • Claude Code lee CLAUDE.md, no AGENTS.md, así que los repos con varias herramientas deben mantenerlos sincronizados.
  • Enlaza simbólicamente CLAUDE.md → AGENTS.md en Mac/Linux, o usa una importación @AGENTS.md de una línea para equipos multiplataforma.
  • Los archivos anidados se fusionan global → raíz → subdirectorio, ganando el archivo más cercano.
  • Rellénalo como un gran CLAUDE.md: resumen, comandos de compilación/prueba, convenciones, seguridad y barreras de protección, corto y veraz.

Siguiente​

Fuentes y lecturas adicionales​