AGENTS.md, el nuevo estándar para configurar agentes de IA

Qué es el archivo AGENTS.md, por qué se ha convertido en la convención portable para configurar agentes de IA y cómo escribir uno bien estructurado.

Publicado el 3 de mayo de 2026

A lo largo de 2025 y 2026 ha emergido una convención que está cuajando rápido en el ecosistema de agentes de IA: usar un archivo AGENTS.md en la raíz del proyecto para definir cómo deben comportarse las herramientas de programación asistida. Es la respuesta natural a la fragmentación que vivimos hace meses, cuando cada herramienta exigía su propio archivo de configuración con sintaxis distinta.

El problema que resuelve AGENTS.md

Antes de que esta convención cuajara, cada herramienta de IA traía su archivo de configuración propio:

  • Claude Code usa CLAUDE.md en la raíz del proyecto.
  • Cursor evolucionó de .cursorrules a .cursor/rules/*.mdc.
  • Aider tiene su propio fichero de configuración en YAML.
  • GitHub Copilot lee .github/copilot-instructions.md.
  • Continue, Cline y otros agentes definían sus propias variantes.

Si trabajabas con dos o tres herramientas a la vez, acababas con varios archivos duplicando esencialmente la misma información: tu stack tecnológico, las convenciones del equipo, los comandos habituales, las advertencias específicas del proyecto. Cualquier cambio implicaba actualizar los archivos en paralelo, con el riesgo de que se desincronizaran.

AGENTS.md propone una solución sencilla: un único archivo Markdown que cualquier agente puede leer al arrancar, con la información que necesita para ser productivo en el proyecto desde el primer minuto.

Qué contiene un AGENTS.md típico

No hay una especificación oficial estricta, pero la práctica común incluye cinco secciones principales. Aquí tienes un ejemplo realista:

# Reglas del proyecto

## Stack
- Framework: Next.js 14 con App Router
- Lenguaje: TypeScript estricto
- Base de datos: PostgreSQL con Prisma
- Estilos: Tailwind CSS, sin CSS modules
- Tests: Vitest + Testing Library

## Comandos habituales
- `pnpm dev`: arranca el servidor de desarrollo
- `pnpm test`: ejecuta los tests
- `pnpm typecheck`: comprueba los tipos
- `pnpm lint`: pasa el linter

## Convenciones
- Componentes funcionales con hooks, nunca clases
- Tests junto al archivo que testean, con sufijo .test.ts
- Commits en español, formato Conventional Commits
- Imports absolutos desde @/ para src/

## Lo que NO debes hacer
- No instales librerías nuevas sin avisar
- No toques los archivos de migración existentes
- No ejecutes git push, deja que lo haga el usuario

## Notas del proyecto
- El módulo de pagos depende de Stripe y no se puede testear en local
- Hay un script de seed en scripts/seed.ts para datos de prueba

Esta estructura le da al agente, en una sola lectura, todo lo que necesita para trabajar como un miembro más del equipo. Cuando empiezas una sesión nueva, no tienes que volver a explicar el stack ni las convenciones.

Por qué Markdown y no JSON o YAML

La elección de Markdown como formato no es casualidad. Los modelos de lenguaje han sido entrenados con cantidades enormes de archivos README.md y documentación técnica, así que interpretan estructuras Markdown de forma muy natural. Hay tres ventajas concretas frente a formatos más estructurados:

  • Legibilidad para humanos y máquinas: el mismo archivo sirve para revisar las reglas tú mismo y para que el agente las aplique.
  • Flexibilidad: puedes mezclar listas, párrafos, ejemplos de código y tablas sin restricciones de schema.
  • Cero curva de aprendizaje: cualquier persona que sepa escribir un README sabe escribir un AGENTS.md.

Si te interesa profundizar en por qué la sintaxis Markdown funciona tan bien con LLMs, lo cubrimos en Markdown en prompts y en Markdown y la IA.

Cómo escribir un buen AGENTS.md

La diferencia entre un AGENTS.md que ayuda al agente y otro que lo confunde se reduce a unos pocos principios.

Sé específico, no genérico

Reglas como "escribe código limpio" o "sé profesional" no aportan información. El agente no tiene criterios para evaluar qué significa "limpio" en tu proyecto. Sustituye por reglas medibles:

- Usa nombres descriptivos: variables en camelCase, componentes en PascalCase
- Funciones de más de 30 líneas se refactorizan
- Cada función pública lleva JSDoc con descripción y ejemplo

Incluye comandos exactos

Un agente productivo necesita saber cómo arrancar el proyecto, cómo testear y cómo desplegar. Cada comando que el agente necesite escríbelo literal:

- Tests: `pnpm test`
- Tests con watch: `pnpm test --watch`
- Test de un archivo concreto: `pnpm test src/lib/auth.test.ts`

Es mucho mejor que escribir "ejecuta los tests" y dejar que el agente adivine.

Separa "qué hacer" de "qué NO hacer"

Las restricciones explícitas evitan errores recurrentes. Una sección dedicada a comportamientos prohibidos hace que el agente sea más conservador con las acciones de alto riesgo:

## Lo que NO debes hacer
- No modifiques archivos en /generated/
- No ejecutes git push ni git reset --hard
- No instales nuevas dependencias sin consultar

Itera sobre fallos reales

La forma más efectiva de mejorar un AGENTS.md es añadir una regla cada vez que el agente se equivoque dos veces de la misma forma. Si descubres que repite un patrón inadecuado, conviértelo en una entrada explícita del archivo.

Mantén una longitud razonable

Un AGENTS.md de 5.000 palabras es contraproducente. El modelo tiene atención limitada incluso con ventanas amplias, y las instrucciones del final pierden peso. Apunta a 300-1.500 palabras. Si necesitas más, particiona el contenido en archivos auxiliares enlazados desde el principal.

Compatibilidad con herramientas actuales

A mayo de 2026, las herramientas que leen o entienden AGENTS.md directamente (o con poca configuración) incluyen a Cursor, Cline, Continue y la mayoría de agentes basados en frameworks como LangChain. Otras como Claude Code mantienen su archivo propio (CLAUDE.md), pero permiten enlazar a AGENTS.md o tratarlo como contexto adicional.

La convención sigue evolucionando y no hay un comité que la "estandarice", pero el patrón es lo bastante simple y útil como para que cada vez más herramientas lo soporten sin fricción.

Errores comunes al escribir AGENTS.md

Estos son los fallos que más se repiten:

  • Reglas vagas: "sé útil", "trabaja bien". Sustituye por criterios concretos.
  • Reglas contradictorias: "sé conciso pero explica con detalle". El agente elegirá una al azar.
  • Demasiado largo: a más de 2.000 palabras la atención del modelo se diluye.
  • Documentación duplicada: si la información ya está en el README, enlaza al README en lugar de copiarla. Los modelos también leen el README cuando lo necesitan.
  • Sin actualizar: el AGENTS.md envejece con el proyecto. Revísalo cuando cambies stack, herramientas o convenciones.

Para terminar

AGENTS.md no es un estándar formal, pero se ha convertido en la forma natural de comunicar el contexto del proyecto a cualquier agente de IA sin atarse a una herramienta concreta. Si trabajas con varios asistentes a la vez o si quieres tener un único punto de verdad para el comportamiento de la IA en tu repo, es la convención más rentable que puedes adoptar hoy.

Recursos relacionados

Esto ha sido todo.

👋 Hola! Soy Edu, me encanta crear cosas y he redactado este tutorial. Si te ha resultado útil, el mayor favor que me podrías hacer es el de compatirlo en Twitter.

para estar al día con mi contenido. 😊