AGENTS.md: qué es y cómo se configura

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.

AGENTS.md es un archivo Markdown que explica a los agentes de programación con IA cómo trabajar en un proyecto. Lo leen sin configurar nada muchas herramientas, desde Codex o Copilot hasta Cursor o Claude Code, y se ha convertido en la forma habitual de dar contexto a cualquier agente.

Qué es AGENTS.md

AGENTS.md es un archivo de texto en Markdown que se coloca en la raíz del repositorio, junto al README. No tiene campos obligatorios ni un esquema que respetar: usas los encabezados que quieras y el agente interpreta el texto. En él se escribe lo que el agente necesita saber para trabajar en el proyecto: qué stack usa, qué comandos lanzar, qué convenciones seguir y qué no debe tocar.

La mejor forma de entenderlo es compararlo con el README. El README está escrito para personas: qué es el proyecto, cómo se instala y cómo se usa. AGENTS.md está escrito para la IA, y recoge los detalles que a una persona le sobrarían pero que un agente necesita para no equivocarse, como el comando exacto para lanzar un test o la carpeta que nunca debe modificar.

Archivos anidados en monorepos

En un repositorio con varios paquetes puedes poner un AGENTS.md dentro de cada uno. El agente lee el más cercano al archivo en el que está trabajando, así que las instrucciones de cada subproyecto mandan sobre las generales de la raíz. Es la forma de dar reglas distintas al frontend y al backend sin mezclarlas en un único archivo.

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

Buena parte de las herramientas de programación con IA leen AGENTS.md directamente, sin configuración. Entre ellas están OpenAI Codex, Google Jules, GitHub Copilot, Cursor, Aider, Zed, Warp, VS Code y Devin. La lista crece cada pocos meses, así que para la relación actualizada consulta la web oficial, agents.md.

Claude Code también lo lee directamente: si el proyecto tiene un AGENTS.md y ningún CLAUDE.md, lo usa como instrucciones del proyecto. Si tienes los dos, por defecto lee solo el CLAUDE.md, pero basta con escribir @AGENTS.md dentro de él para incluirlo. Así el contenido común vive en un único archivo que leen todas las herramientas, y el CLAUDE.md solo añade lo específico de Claude. Lo explicamos en CLAUDE.md, el archivo de instrucciones de Claude Code.

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. 😊