Llega un día en que tu proyecto tiene reglas —cómo se arranca, con qué comando se prueba, qué NO se toca, cómo se escriben los commits— y más de un cerebro artificial pasa por él: construyes con uno, revisas con otro, y mañana cambias de modelo para gastar menos créditos. El problema es que ese conocimiento vive en tu cabeza, y cada agente nuevo empieza en cero: le explicas todo, cierras la sesión, y a la semana lo repites otra vez (o se lo repites a otra IA distinta). AGENTS.md mata ese peaje. Es un estándar abierto —un "README para agentes"— que hoy leen más de 25 herramientas (OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Zed, Windsurf, Devin, Claude Code…) y usan más de 60.000 proyectos. Un archivo de Markdown plano, sin configuración rara, en la raíz de tu proyecto: escribes tus reglas UNA vez y las obedecen todos los agentes, hoy y mañana. Aquí entenderás por qué lo necesitas, qué lleva dentro, el matiz de AGENTS.md vs CLAUDE.md sin duplicar nada, y el prompt que te lo genera perfecto mirando tu código de verdad. Cero humo.
La necesidad aparece el día en que tu proyecto tiene reglas y más de un cerebro artificial pasa por él. Puede ser que uses Claude Code para construir, otra herramienta para revisar, y de vez en cuando abras Cursor o Copilot para algo puntual. O que mañana cambies de agente para ahorrar créditos. En todos esos casos hay conocimiento que no vive en el código: cómo se arranca el entorno, con qué comando se corren las pruebas, qué carpetas son sagradas y no se tocan, cómo quieres que se escriban los mensajes de guardado. Ese conocimiento hoy vive en tu cabeza — y cada agente nuevo empieza en cero, sin saber nada de eso.
El dolor es silencioso y se paga en cuotas. La sesión de hoy con tu IA sabe perfectamente cómo funciona tu proyecto porque se lo fuiste explicando durante horas. Pero ese conocimiento no queda guardado en ningún lado: cuando cierras la conversación, se evapora. Mañana abres una sesión nueva —o cambias de modelo para gastar menos— y estás otra vez en la casilla de salida, repitiendo "recuerda que las pruebas se corren con este comando", "no toques la carpeta de pagos", "los commits van en este formato".
¿Por qué pasa? Porque cada agente arranca ciego: solo ve tu código, no ve tus reglas ni tus costumbres. Y como cada herramienta guardaba sus instrucciones a su manera —Claude en un archivo, Cursor en otro, Copilot en otro— tenías que mantener el mismo conocimiento escrito tres o cuatro veces. Un caos que se desincroniza solo: cambias una regla en un archivo y se te olvida en los demás.
AGENTS.md es un README para agentes. Igual que el README de toda la vida le cuenta a un humano de qué va tu proyecto, AGENTS.md le cuenta a cualquier IA de código cómo comportarse dentro de él. Es un archivo de texto plano (Markdown) que pones en la raíz de tu proyecto, y ya. Sin configuración rara, sin código, sin ceremonias.
Lo que lo vuelve poderoso no es el formato —es que se convirtió en un estándar abierto que hoy leen más de 25 herramientas distintas: OpenAI Codex, Cursor, GitHub Copilot, Gemini CLI, Google Jules, Aider, Zed, Windsurf, Devin, JetBrains Junie, Warp, goose y más. Más de 60.000 proyectos de código abierto ya lo usan. Escribes tus reglas UNA vez, y funcionan con la IA que uses hoy y con la que uses mañana. Dejas de estar casado con una sola herramienta.
El estándar abierto AGENTS.md — el "README para agentes" que hoy leen 25+ herramientas de código con IA. Guía, ejemplos y la especificación completa. Administrado por la Agentic AI Foundation (Linux Foundation). ~23k★.
Aquí viene la mejor noticia: no hay que aprenderse un formato rígido. AGENTS.md es Markdown normal y corriente — títulos con #, listas con guiones, texto. No lleva esa cabecera técnica llena de dos puntos y llaves (lo que los programadores llaman YAML frontmatter): nada de eso es obligatorio. Escribes en secciones con el nombre que quieras, y el agente lee lo que le pongas. Punto.
Dicho eso, hay cinco bloques que casi todo buen AGENTS.md incluye — porque son justo el conocimiento que se evapora entre sesiones. Piénsalos como los cinco cajones del manual del puesto:
Este recurso no es de los que se aplican todos los días — es de los que se hacen bien una vez y se retocan de tanto en tanto. La constancia aquí no está en la frecuencia, sino en dos momentos concretos donde no puedes olvidarte de él:
Aquí es donde la gente se enreda, así que vamos claros. Antes de que existiera el estándar, cada herramienta inventó su propio archivo de reglas: Claude Code lee un CLAUDE.md, Cursor leía un .cursorrules, y así cada una. El problema evidente: si usabas tres herramientas, mantenías tres archivos con el mismo conocimiento, desincronizándose solos. AGENTS.md nació justo para acabar con ese desorden: una sola fuente de verdad que leen todas.
# CLAUDE.md # Las reglas del proyecto viven en AGENTS.md (fuente única). # Claude Code las carga con esta línea de importación: @AGENTS.md # Debajo, solo lo específico de Claude Code que NO aplica # a los demás agentes (si es que hay algo).
¿Cuándo usar cuál? Fácil: AGENTS.md para todo lo que quieres que obedezca cualquier agente (el 95% de tus reglas). El archivo propio de una herramienta (CLAUDE.md, .cursorrules) solo para lo que es exclusivo de esa herramienta — un comando que solo ella entiende, un ajuste que solo a ella le sirve. Si dudas, va en AGENTS.md. La regla mental: escribe para todos por defecto; escribe para uno solo por excepción.
Si vienes de la idea de escribir una especificación antes de construir (el qué quieres que se construya), AGENTS.md es la otra mitad del par — y no se pisan, se complementan. La spec gobierna QUÉ se construye: la funcionalidad, el objetivo, el resultado. AGENTS.md gobierna CÓMO se comporta cualquier agente mientras lo construye: con qué comandos, qué reglas, qué no tocar. Una es el plano del edificio; la otra, las normas de seguridad de la obra. Necesitas las dos.
Aquí está el atajo. No tienes que escribir el archivo a mano ni pensar en cada sección: le das este prompt a tu agente de código dentro de tu proyecto, y él lo redacta por ti mirando cómo está armado tu código de verdad. Tú solo revisas y ajustas. Cópialo tal cual, rellena los corchetes con lo que sepas, y déjalo trabajar:
Quiero crear un archivo AGENTS.md en la raíz de mi proyecto: el "README para agentes" del estándar abierto (agents.md) que leen las herramientas de IA de código. Es Markdown plano, SIN cabecera YAML. Guíame en lenguaje simple, asumiendo que no soy programador. Primero, EXPLORA mi proyecto de verdad (revisa la estructura de carpetas, el package.json o equivalente, y cómo está organizado) para NO inventar nada. Luego redacta un AGENTS.md con estas secciones, en Markdown limpio: 1. Resumen del proyecto — 2 o 3 frases de qué es y qué tecnologías usa (dedúcelo del código). 2. Preparar el entorno — los comandos reales para instalar y arrancar el proyecto de cero. 3. Cómo se prueba — el comando exacto de las pruebas y del chequeo de errores/tipos, para que cualquier agente verifique su trabajo antes de darlo por bueno. 4. Reglas de estilo — el idioma del código y las convenciones que detectes (comillas, nombres, formato). 5. Commits y PRs — este es mi formato de mensajes de commit: [descríbelo, o dime si no tengo uno y propón uno bueno]. 6. Límites · lo que NO se toca — marca como INTOCABLES sin permiso explícito estas carpetas/archivos sagrados: [lista aquí lo sensible: pagos, secretos, configuración, migraciones… lo que tengas]. Deja claro que un agente debe PARAR y preguntar antes de modificarlos. Reglas para redactarlo: - Solo afirma cosas que puedas verificar mirando mi código. Si algo no lo sabes, pon un marcador [POR CONFIRMAR] en vez de inventarlo. - Que sea conciso y accionable, no una novela. Un agente lo lee entero antes de trabajar. - Si mi herramienta principal ya tiene su propio archivo de reglas (por ejemplo CLAUDE.md), NO dupliques el contenido: haz que ese archivo importe el AGENTS.md con una sola línea, y déjame AGENTS.md como fuente única de verdad. Al terminar, muéstrame el archivo completo y explícame en una frase qué guardaste en cada sección, para yo revisarlo.
[POR CONFIRMAR] cuando no esté segura — nada de humo, nada de reglas inventadas. Tu trabajo se reduce a leer el borrador y corregir lo que no cuadre con cómo trabajas tú. De experto a revisor: exactamente el rol que te toca.Como en toda la serie, hay dos formas de hacer esto y ninguna te obliga a tocar la terminal si no quieres:
AGENTS.md en la carpeta raíz de tu proyecto, y escribes las cinco secciones tú mismo copiando la plantilla de abajo. También vale — es solo texto.Si vas por el camino manual, esta es la plantilla mínima lista para copiar y rellenar. Cámbiala a tu gusto: recuerda que no hay formato obligatorio.
# AGENTS.md ## Resumen del proyecto [Qué es y con qué está hecho. 2-3 frases.] ## Preparar el entorno [Comandos para instalar y arrancar de cero.] ## Cómo se prueba - Pruebas: [comando exacto] - Chequeo de errores/tipos: [comando exacto] > Corre esto y déjalo en verde antes de dar por terminado un cambio. ## Reglas de estilo [Idioma del código, convenciones de nombres/formato.] ## Commits y pull requests [Tu formato de mensajes de commit. Ejemplo de uno bueno.] ## Límites · NO tocar sin permiso - [Carpeta o archivo sagrado 1 — por qué es sensible] - [Carpeta o archivo sagrado 2] > Ante cualquiera de estos: PARA y pregunta antes de modificar.
AGENTS.md, en la raíz. Deja de repetirte en cada sesión.Únete a 4.200+ creadores. Sin tarjeta. Construye tu primera app con IA en minutos.