AGENTS.md es un archivo de texto en tu repositorio con las instrucciones para los agentes de código: cómo instalar, cómo correr los tests y qué convenciones seguir. Es un formato abierto que leen muchas herramientas, como Codex, Cursor o GitHub Copilot. La idea es tener un solo archivo de reglas, sin importar qué agente abra el proyecto.
Una pregunta de la app. Elige una respuesta.
Usas dos agentes y cada uno lee otro archivo de reglas. ¿Cómo evitas que se contradigan?
Funciona el primer día. Después cambias una regla en un archivo y te olvidas del otro.
Queda una sola fuente: el segundo archivo importa o enlaza al primero, y lo que cambias vale para los dos.
Ocupan lugar en cada mensaje y dependen de que te acuerdes. El archivo existe para no repetirlas.
El README le explica el proyecto a una persona; AGENTS.md se lo explica a un agente de código. Ahí va lo que el agente no puede adivinar: el comando que corre los tests, la convención de nombres, la carpeta que no se toca. No tiene campos obligatorios: es Markdown común, con los títulos que quieras.
En un repo con varias partes, cada carpeta puede tener el suyo, y el agente usa el más cercano al archivo en el que trabaja. Lo que el archivo dice entra en el prompt del modelo y ocupa lugar en su ventana de contexto en cada sesión, así que conviene corto. A octubre de 2026, el formato lo cuida la Agentic AI Foundation, dentro de la Linux Foundation.
A octubre de 2026, Codex, Cursor, GitHub Copilot, Gemini CLI y muchos otros leen AGENTS.md. Claude Code nació leyendo su propio CLAUDE.md, y sus versiones recientes también leen AGENTS.md, pero con una condición: por defecto, sólo si el proyecto no tiene un CLAUDE.md. Si están los dos, lee CLAUDE.md y deja AGENTS.md afuera, salvo que cambies esa opción en su configuración.
Al revés pasa algo parecido: Codex no lee CLAUDE.md salvo que lo configures. Por eso, si tu equipo usa varias herramientas, no alcanza con tener los dos archivos: hay que decidir cuál manda.
Lo más simple: las reglas viven en AGENTS.md y el CLAUDE.md sólo lo importa con una sola línea: @AGENTS.md. Claude Code lee primero lo importado y después lo que agregues abajo, que queda para lo propio de Claude. Así cambias una regla en un lugar y vale para todos.
Otra opción es que CLAUDE.md sea un enlace simbólico a AGENTS.md. Funciona, pero si alguien del equipo usa Windows el enlace puede llegarle como un archivo de una línea. Y si una instrucción larga sirve sólo para una tarea, como publicar una versión, suele quedar mejor en una skill, que se carga cuando hace falta.
@AGENTS.md
## Claude Code
Use plan mode for changes under src/billing/.«Si tengo los dos archivos, Claude lee los dos.» Por defecto, no: lee CLAUDE.md. «Escribo en CLAUDE.md "lee también AGENTS.md" y listo.» Así el agente lo abre sólo si decide hacerlo; la importación con @ lo carga siempre. «Copio las reglas en los dos.» Funciona hasta el día en que cambias una y te olvidas de la otra.