Qué es AGENTS.md y cómo escribir el tuyo en 30 minutos

Material práctico sobre vibe coding y trabajo con agentes: documentación de Ailoot.

AGENTS.md en un párrafo#

A continuación, se presenta el formato a partir de agents.md, la documentación de OpenAI Codex, JetBrains Junie, Cursor Rules Docs, el registro de cambios de GitHub Copilot Coding Agent y el comunicado de prensa de Linux Foundation sobre Agentic AI Foundation. Todas las cifras y funciones están actualizadas al 30 de mayo de 2026. La compatibilidad de Claude Code con AGENTS.md se describe según la documentación de Anthropic, con una actualización del 24 de septiembre de 2026.

Si no tienes ni idea de qué es este zoológico de herramientas del mercado ni de por qué necesitan un archivo compartido, lee primero la guía «Con qué programar en 2026: 8 herramientas de IA, de Claude Code a Antigravity». Este artículo se centra específicamente en el formato AGENTS.md y en cómo escribir uno propio en 30 minutos.

¿Qué es AGENTS.md y de dónde viene?#

Antes, cada herramienta de IA tenía su propio archivo de reglas: Anthropic tenía CLAUDE.md, Cursor tenía .cursorrules, GitHub tenía .github/copilot-instructions.md, Aider tenía .aider.conf.yml y JetBrains tenía .junie/guidelines.md. Si tu equipo tenía tres agentes distintos, eso significaba mantener tres archivos paralelos con el mismo contenido que, en una semana, acababan divergiendo.

OpenAI fue la primera en cansarse de eso. En agosto de 2025 publicó Codex CLI y lanzó a la vez agents.md como formato abierto. En el sitio se lee:

«Piensa en AGENTS.md como un README para agentes».

(agents.md, traducido del inglés)

La idea principal es que AGENTS.md complementa README. README está escrito para las personas: «qué es el proyecto, cómo ejecutarlo localmente y cómo contribuir». AGENTS.md está escrito para el agente: comandos de shell exactos, criterios verificables para determinar que algo está «hecho» y límites como «no toques esto nunca».

En el sitio se lee:

«AGENTS.md complementa README: contiene contexto adicional, a veces detallado, que el agente necesita — pasos de compilación, pruebas y convenciones que llenarían README o que simplemente no necesitan los colaboradores humanos».

(agents.md, traducido del inglés)

En septiembre de 2025, GitHub Copilot Coding Agent ya admitía el formato (registro de cambios, 28.08.2025). En diciembre se habían sumado Cursor, Junie, Gemini CLI, Aider y otra docena de herramientas. El 9 de diciembre de 2025, Linux Foundation creó la Agentic AI Foundation (AAIF): sus tres proyectos fundadores eran AGENTS.md de OpenAI, MCP de Anthropic y goose de Block. Sus miembros fundadores eran AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft y OpenAI. Para el 24 de febrero de 2026, la fundación ya incluía 146 organizaciones, entre ellas Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath y Hitachi.

A partir de entonces, AGENTS.md dejó de ser «otra cosa más de OpenAI» y pasó a ser un estándar de facto.

Qué agentes de IA leen AGENTS.md y cuáles no#

Tabla de compatibilidad al 30 de mayo de 2026; la fila de Claude Code se actualizó el 24 de septiembre de 2026:

Anthropic fue el último de los grandes actores en sumarse. En agosto de 2025 se abrió en el repositorio oficial anthropics/claude-code la incidencia #6235, que solicitaba compatibilidad con AGENTS.md.

La incidencia permaneció abierta casi un año y se cerró el 17 de agosto de 2026; la versión 2.1.277, que incluía compatibilidad con AGENTS.md, salió el 18 de septiembre. La lógica de Anthropic es la siguiente: CLAUDE.md tiene prioridad y AGENTS.md se lee cuando no hay un archivo CLAUDE.md en la carpeta de trabajo ni en ninguna carpeta superior. Según la documentación, funciona así:

El detalle: un archivo personal CLAUDE.local.md también cuenta, y entonces Claude Code deja de leer AGENTS.md. Puedes cambiar este comportamiento en /config, en Project instructions; por ejemplo, para que Claude Code lea ambos archivos a la vez. En las versiones anteriores a la 2.1.277, AGENTS.md no se carga automáticamente; la línea @AGENTS.md en CLAUDE.md sigue siendo la solución alternativa.

En qué se diferencia AGENTS.md de CLAUDE.md y .cursorrules#

Comparación de los cuatro formatos al 30 de mayo de 2026:

La idea clave: AGENTS.md puede contener las instrucciones compartidas del proyecto, mientras que la carga y los ajustes personales requieren una configuración independiente en cada cliente. Claude Code tiene CLAUDE.local.md para eso, y Cursor tiene archivos .mdc locales bajo user. AGENTS.md por sí solo no ofrece esa opción: necesitas combinarlo con otros archivos o acordar con el equipo escribir las reglas personales en secciones ignoradas por Git.

Otro detalle importante son los monorrepositorios. Codex y Cursor aplican la regla «gana el AGENTS.md más cercano»:

«En un monorrepositorio, coloca un AGENTS.md separado dentro de cada paquete. Los agentes leen automáticamente el archivo más cercano en el árbol de directorios, y ese es el que prevalece».

(agents.md, traducido del inglés)

agents.md menciona que el monorrepositorio principal de OpenAI contiene 88 archivos AGENTS.md para distintos subpaquetes. Si trabajas en un monorrepositorio, distribuye las reglas por niveles: las generales en la raíz y las específicas en las subcarpetas.

Qué debe incluir un buen AGENTS.md#

El sitio agents.md propone un formato flexible: «cualquier Markdown». Pero el 80 % de los buenos archivos que se encuentran por ahí contienen las mismas ocho secciones. Regla principal: cada punto debe ser un comando exacto o un ejemplo concreto. El agente ignorará una idea abstracta como «escribe código limpio».

1. Descripción del proyecto — 2–3 líneas. Qué es el proyecto, para quién es y cuál es su objetivo principal. Sin marketing. Ejemplo: «Bot de Telegram para dar la bienvenida a quienes se apuntan a un taller de pago. Stack: Next.js 14, Prisma, PostgreSQL. Se activa con un nuevo registro en purchases.»
2. Comandos de configuración — comandos de shell exactos para ejecutarlo localmente. npm install, npm run dev, npm run build. Nada de «así es como solemos hacerlo».
3. Estilo de código / convenciones — reglas concretas con un ejemplo, no «escribe con claridad». Por ejemplo: «TypeScript estricto, comillas simples, sin exports predeterminados, nombres de componentes en PascalCase, hooks que empiezan por use».
4. Consejos sobre el entorno de desarrollo — dónde se encuentra lo importante. Qué variables hacen falta en .env, dónde se guardan los secretos, qué puertos están en uso y cómo trabajar con la DB local.
5. Instrucciones de prueba — cómo ejecutar una prueba específica y qué significa que esté «en verde». Por ejemplo: npm test -- --testPathPattern=user-auth; se espera que pase el 100 %.
6. Pautas para PR y commits — formato de los mensajes de commit, lista de comprobación previa a la PR (pruebas, linter, documentación) y quién aprueba.
7. Consideraciones de seguridad — lo que nunca debe ocurrir. «No incluyas .env en un commit. Los secretos solo deben estar en Vault. No muestres datos personales de los usuarios en los registros».
8. Límites / Nunca hagas esto — prohibiciones con una alternativa. «No uses git push --force en main. Si necesitas revertir, usa git revert o git reset en una rama de funcionalidad».

En cada sección, aplica el principio «un comando en vez de una idea». El agente ignorará «ten cuidado con las migraciones». Seguirá «Antes de alembic upgrade head, ejecuta alembic check. Si da error, no apliques la migración; pregúntame».

Plantilla de AGENTS.md lista para usar (copia y adapta)#

# AGENTS.md

## Project overview

<project-name> - <one phrase describing its purpose>.
Stack: <Next.js / Python / Go / ...>.
Main entities: <users, orders, posts ...>.
Details for people are in README.md.

## Setup commands

```bash
# first install
npm install
cp .env.example .env  # then fill in manually; see list below

# run
npm run dev           # dev server on :3000
npm run build         # production build
npm run start         # run production build
```

## Dev environment

- Node 20+ (via nvm: `nvm use 20`)
- PostgreSQL 16 locally on :5432 (`docker-compose up postgres`)
- Redis is optional, needed only for queues (`docker-compose up redis`)
- `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET`
- Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons (unless ESLint requires them)
- Imports: external first, then internal via `@/`, then relative
- Components in PascalCase; hooks start with `use`
- No `any` without an explicit comment explaining “why it can’t be typed”

Example of a good module:

```ts
import { z } from 'zod'

const UserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(2),
})

export function parseUser(raw: unknown) {
  return UserSchema.parse(raw)
}
```

## Testing

```bash
npm test                                # all tests
npm test -- --testPathPattern=auth      # auth only
npm test -- --watch                     # watch mode
```

All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do.

## Pull request guidelines

- Commit format: `<type>(<scope>): <description>` (`feat(auth): add magic-link`)
- Before PR: `npm run build && npm test && npm run lint`
- PR description = what changes, why, and how to test
- Don’t approve your own PR—always wait for human review

## Security

- Secrets only in `.env` and Vault, never in code
- Don’t log personal data (email, phone, name)
- When working with the production DB, use read-only queries only unless explicitly authorized
- Don’t hardcode external service API keys (Stripe, OpenAI) in tests

## Never do this

- Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR
- Don’t run DB migrations without `alembic check` (or the equivalent in your ORM)
- Don’t use `npm install -g` or `sudo` for project dependencies
- Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM)

En promedio, la plantilla tiene entre 80 y 120 líneas. Si el archivo supera las 150 líneas, es señal de que debes reorganizarlo: mueve algo a docs/, enlaza a otro documento o condensa algún punto en una línea. En la práctica, los archivos de 100–150 líneas funcionan mejor; a partir de ahí, las mejoras de calidad empiezan a revertirse.

Qué 5 reglas hacen que AGENTS.md sea realmente útil#

1. Comandos en vez de ideas. Un agente no entiende «ten cuidado con las migraciones». Seguirá alembic check antes de alembic upgrade head. Los agentes trabajan con comandos y condiciones, no con estados de ánimo. Formula todas las reglas clave como «haz X; si no, haz Y».

2. Prohibiciones con una alternativa. El agente acaba ignorando discretamente un simple «no hagas force push» tras dos o tres prompts. Funciona la combinación «no hagas X; en su lugar, haz Y». Ejemplo: «No uses git push --force en main; si necesitas revertir, usa git revert o abre una PR nueva».

3. Una sola fuente de verdad. El AGENTS.md de la raíz es la fuente de verdad para todo el proyecto. Si tienes un monorrepositorio, usa archivos AGENTS.md anidados en las subcarpetas y sigue la regla de que «gana el más cercano». Nada de archivos paralelos con instrucciones contradictorias.

4. Criterios de finalización verificables. «Las pruebas deben pasar» no sirve de nada. Un criterio exacto sería: npm test devuelve el código de salida 0 y no imprime FAIL en stdout. «El código debe estar limpio» tampoco sirve. Un criterio exacto sería: npm run lint termina sin advertencias. Un agente solo entiende qué significa «terminado» cuando describes la condición de forma explícita.

5. Un archivo de menos de 150 líneas. Por encima de 150 líneas, las métricas empiezan a deteriorarse: el agente dedica más contexto a leer y pasa por alto reglas importantes. Si no cabe, mueve los detalles a docs/architecture.md y enlázalo desde AGENTS.md; deja en este solo los comandos y los límites.

Qué 10 errores convierten AGENTS.md en basura#

1. Reglas vagas sin comandos. El agente ignorará «ten cuidado con las migraciones»; esa frase no significa nada para él. Solo funciona un comando específico con una condición: «Ejecuta alembic check antes de alembic upgrade head. Si hay un error, no apliques la migración; pregúntame».

2. «Código limpio». Una frase inútil. Sustitúyela por un patrón específico: «Usa componentes funcionales con hooks. Ejemplo: function LoginForm() { const [email, setEmail] = useState(''); ... }»

3. Prosa sin estructura. Si AGENTS.md tiene 300 líneas de prosa sin encabezados, el agente gastará 80K tokens de contexto en pasajes irrelevantes y pasará por alto lo importante. Usa encabezados H2/H3, secciones breves y listas con viñetas.

4. Un archivo de más de 150 líneas. Las métricas de calidad empeoran al superar este umbral. Divide el contenido entre un archivo principal y enlaces a los detalles en docs/.

5. Más de 30 prohibiciones sin alternativas. Si el archivo contiene una larga lista de «no hagas X, no hagas Y» sin explicar «haz Z en su lugar», el agente avanzará a ciegas.

6. Duplicar README.md. Si ya has explicado en README cómo instalar y ejecutar el proyecto, no lo copies en AGENTS.md. En su lugar, remite a README en una línea y describe en AGENTS.md lo que necesita el agente pero no los colaboradores humanos.

7. Incluir secretos directamente. AGENTS.md puede ser público porque está en Git. No incluyas claves API, tokens ni contraseñas reales. Limítate a indicar dónde encontrar los secretos: «Consulta Vault: secret/staging/db».

8. Prioridades contradictorias sin orden. «Avanza rápido» + «mantén un 90 % de cobertura de pruebas» deja al agente sin saber qué elegir. Indica expresamente el orden: «Primero, cobertura de pruebas ≥80 %; después, velocidad. Si entran en conflicto, las pruebas tienen prioridad».

9. Documentación obsoleta. Una descripción de la arquitectura que habla de REST+polling cuando en realidad ya se usan WebSockets. El agente sigue la descripción desactualizada y rompe la arquitectura. Regla: actualiza AGENTS.md en la misma PR que el código siempre que cambie la arquitectura.

10. Arquitectura excesiva para una tarea sencilla. Si alguien pide cambiar dos líneas de una configuración, el agente no debería tener que leer toda la topología de 14 microservicios. Mueve la arquitectura «en profundidad» a docs/architecture.md; en AGENTS.md, deja solo «si la tarea tiene que ver con arquitectura, lee docs/architecture.md».

El estudio de GitHub Blog sobre más de 2.500 repositorios con AGENTS.md indica su principal conclusión:

«La mayoría de los archivos para agentes fallan porque son demasiado generales. “Eres un asistente de programación útil” no funciona».

(GitHub Blog, traducido del inglés)

Cómo mantener AGENTS.md y CLAUDE.md en el mismo repositorio#

La principal pregunta práctica es cómo convivir con ambos archivos sin duplicar contenido. Hay tres escenarios:

Escenario 1: solo Claude Code. Conserva CLAUDE.md y usa todas las funciones de Claude Code: ~/.claude/CLAUDE.md para instrucciones de usuario, CLAUDE.md para el proyecto, CLAUDE.local.md para ajustes personales, @import para incluir otros archivos y .claude/skills/ para skills especializados. AGENTS.md no hace falta.

Escenario 2: varios clientes de programación. Conserva las reglas compartidas en AGENTS.md y conecta y verifica cada cliente por separado. Gemini CLI permite configurar el nombre del archivo de contexto; Aider puede cargar un archivo mediante su configuración de lectura. Son vías explícitas, no un descubrimiento automático idéntico.

Inicia una sesión nueva en un repositorio de prueba inocuo y añade una instrucción única e inofensiva, por ejemplo «incluye el marcador instructions-loaded en la respuesta de prueba». Revisa la vista documentada de archivos cargados o los registros del cliente, además de su respuesta. Repite la comprobación en cada cliente y versión que uses. Que el modelo afirme haber leído el archivo no es una prueba independiente de carga; una comprobación correcta no demuestra compatibilidad en todas las demás herramientas.

Escenario 3: un equipo mixto (Claude Code + otras herramientas). Es la configuración más común en 2026. La solución consiste en hacer que AGENTS.md sea el archivo principal. Si no tienes reglas exclusivas para Claude Code, no crees CLAUDE.md: desde la versión 2.1.277, Claude Code lee AGENTS.md cuando el proyecto no tiene CLAUDE.md. Si sí tienes esas reglas, convierte CLAUDE.md en un enlace simbólico o en un archivo breve que incluya @AGENTS.md.

Antes de cambiar cualquier archivo, inspecciona ambos y guarda copias. Si existen los dos, combina sus instrucciones compartidas compatibles en AGENTS.md y conserva las específicas de Claude en CLAUDE.md con una importación @AGENTS.md. Conserva los enlaces simbólicos existentes en lugar de sustituirlos.

Solo para un CLAUDE.md normal cuando no exista AGENTS.md, esta protección de shell en macOS/Linux rechaza sobrescribir un destino o enlace simbólico existente:

if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then
  printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2
elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md
else
  printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2
fi

Tras un cambio de nombre correcto, CLAUDE.md es un enlace simbólico a AGENTS.md. Todos los agentes que leen AGENTS.md ven el mismo contenido. Claude Code, que lee CLAUDE.md, ve ese contenido a través del enlace simbólico.

En Windows, crear un enlace simbólico requiere el modo de desarrollador (o permisos de administrador), lo que puede resultar incómodo para todo el equipo. Una alternativa es crear un CLAUDE.md breve que importe AGENTS.md:

# CLAUDE.md

@AGENTS.md

## Claude Code specific

- Use .claude/skills/ for specialized prompts
- When working with Skills, consult .claude/skills/INDEX.md
- Use Plan Mode before major changes (Shift+Tab)

En Claude Code, esta sintaxis incorpora AGENTS.md con una sola línea y permite añadir debajo instrucciones específicas de Claude Code. Si más adelante quieres quitar AGENTS.md, basta con eliminar la importación. Esta línea no hace que se lea dos veces: según la documentación de Claude Code, AGENTS.md no se carga dos veces, aunque Claude Code también pueda leerlo por su cuenta.

Estructura canónica para un equipo con varias herramientas en 2026:

repo-root/
├── AGENTS.md                              # fuente de verdad, ≤150 líneas
├── CLAUDE.md                              # solo si hay reglas específicas de Claude: enlace simbólico → AGENTS.md O @AGENTS.md + añadidos
├── .cursor/rules/                         # ajustes específicos de Cursor
├── .github/copilot-instructions.md        # «Consulta AGENTS.md», si se usa
└── docs/architecture.md                   # arquitectura detallada referenciada en AGENTS.md

Encontrarás más información sobre CLAUDE.md en la guía «Cómo configurar CLAUDE.md correctamente». Para saber más sobre por qué un agente necesita un archivo extenso de instrucciones, lee «Qué es la ingeniería de contexto».

Qué cambió en 2026: por qué la AAIF puso AGENTS.md bajo el amparo de Linux Foundation#

La principal historia política de mayo de 2026 en el ámbito de la programación con IA no fue el lanzamiento de otro modelo, sino la consolidación de formatos. Antes, cada proveedor tenía su propio archivo de reglas, algo cómodo para los proveedores pero engorroso para los equipos que trabajaban con varias herramientas.

En un comunicado de prensa fechado el 9 de diciembre de 2025, Linux Foundation anunció Agentic AI Foundation como paraguas para tres formatos:

• AGENTS.md de OpenAI: un formato de archivo de instrucciones para agentes
• Model Context Protocol (MCP) de Anthropic: un protocolo para conectar herramientas externas con agentes
• goose de Block: un framework de agentes de código abierto

Del comunicado de prensa de Linux Foundation:

«Reunir estos proyectos bajo el paraguas de AAIF garantiza que puedan desarrollarse con la transparencia y la estabilidad que solo ofrece la gobernanza abierta».

(Comunicado de prensa de Linux Foundation, 9 de diciembre de 2025, traducido del inglés)

Para el 24 de febrero de 2026, 146 organizaciones formaban parte de AAIF (97 nuevos miembros en dos meses). Entre los nuevos miembros Gold se encontraban Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express y Autodesk. Anthropic está en el nivel Platinum y promueve MCP. OpenAI está en el nivel Platinum y promueve AGENTS.md. Block está en el nivel Platinum con goose.

Esto cambia el posicionamiento de AGENTS.md: pasó de ser un «formato de OpenAI» a ser un estándar del sector. En la primavera de 2026, Claude Code aún seguía al margen, pero en septiembre aprendió a leer AGENTS.md por su cuenta con la versión 2.1.277. CLAUDE.md no ha desaparecido y, de forma predeterminada, sigue teniendo prioridad si está en el proyecto.

Un punto de partida práctico es guardar las reglas compartidas del proyecto en AGENTS.md y configurar la importación, el archivo intermedio o la lectura explícita que requiera cada cliente. Para Claude Code, comprueba la versión instalada y la prioridad de los archivos de instrucciones antes de decidir entre una importación en CLAUDE.md o un enlace simbólico. Verifica la carga en cada cliente; aquí no se ha establecido ningún porcentaje de cobertura.

Qué viene después#

AGENTS.md es el primer elemento de «cómo ponerse de acuerdo con un agente para que funcione de forma predecible». El segundo elemento es una carpeta de conocimiento del proyecto, que contiene contexto empresarial, audiencia, productos y precios. El tercer elemento es la ingeniería de contexto, que lo integra todo: qué archivos ve el agente en cada paso, cómo se conserva el estado entre sesiones y cómo cambiar entre distintos modelos.

Material práctico: documentación de Ailoot.

Más materiales y herramientas: Ailoot.