Introduccion y Motivacion

El problema

Usas un agente de codigo IA (Claude Code, Cursor, Codex, Copilot). Le pides que agregue un endpoint. El agente:

1. Explora el repositorio para entender la estructura
2. Adivina que framework usas
3. Genera codigo con convenciones que no son las de tu proyecto
4. Usa npm cuando tu proyecto usa pnpm
5. Crea tests con Jest cuando tu usas Vitest

El resultado: pierdes tiempo corrigiendo lo que el agente no sabia. El agente no es malo, le falta contexto.

La solucion: un README para agentes

AGENTS.md es un archivo markdown en la raiz de tu repositorio que le dice a los agentes de codigo exactamente lo que necesitan saber:

• Que comandos ejecutar para build, test y lint
• Que convenciones de codigo seguir
• Que archivos no tocar
• Como esta organizado el proyecto

Es como un README.md, pero optimizado para agentes en vez de humanos.

Por que un archivo separado

La pregunta obvia: ¿por que no poner esto en el README?

README.md	AGENTS.md
Dirigido a humanos	Dirigido a agentes IA
Quick start, contribucion	Comandos exactos, convenciones
Descripcion narrativa	Instrucciones precisas y ejecutables
Puede ser extenso	Debe ser conciso (presupuesto de tokens)

Mantenerlos separados tiene beneficios concretos:

• Predictibilidad: los agentes saben exactamente donde buscar instrucciones
• README limpio: no contaminas la documentacion humana con instrucciones para IA
• Precision: puedes ser mucho mas directo y tecnico sin preocuparte por legibilidad humana

El problema de la fragmentacion

Antes de AGENTS.md, cada herramienta tenia su propio archivo:

Herramienta	Archivo de contexto
Claude Code	CLAUDE.md
Gemini CLI	GEMINI.md
AMP	AGENT.md
Cursor	.cursorrules
Windsurf	.windsurfrules

Resultado: los proyectos terminaban con 3-5 archivos diciendo lo mismo. Mantenimiento imposible, divergencia inevitable.

AGENTS.md como estandar unificado

En 2025, OpenAI (Codex), Google (Jules), AMP, Cursor, Factory y otros se unieron para estandarizar un unico formato: AGENTS.md.

El estandar esta gobernado por la Agentic AI Foundation bajo la Linux Foundation. No es propiedad de ninguna empresa.

Caracteristicas del estandar

• Sin schema obligatorio: es Markdown puro, sin JSON, sin YAML, sin sintaxis especial
• Cross-platform: un archivo funciona con 25+ herramientas
• Jerarquico: soporta archivos anidados para monorepos
• Ligero: no requiere instalacion ni configuracion

Adopcion

• Mas de 60,000 repositorios open-source lo usan
• Proyectos con AGENTS.md detallado promedian 35-55% menos bugs generados por agentes
• Vercel reporto que AGENTS.md alcanzo 100% de pass rate en sus evaluaciones, vs 53% sin documentacion

Como funciona

El flujo es simple:

1. Creas AGENTS.md en la raiz del repo
2. Agregas secciones relevantes (comandos, convenciones, boundaries)
3. Lo commiteas junto al codigo
4. Los agentes lo descubren y leen automaticamente

No hay CLI, no hay instalacion, no hay configuracion. Los agentes simplemente buscan el archivo y lo leen antes de empezar a trabajar.

Resolucion de conflictos

Cuando hay instrucciones superpuestas:

1. Prompt del usuario siempre gana (maxima prioridad)
2. AGENTS.md mas cercano al directorio de trabajo tiene prioridad
3. AGENTS.md de la raiz aplica como fallback general

Que NO es AGENTS.md

• No reemplaza documentacion: es complemento, no sustitucion
• No es un prompt: es contexto persistente, no una instruccion de una sola vez
• No es obligatorio: los agentes funcionan sin el, pero funcionan mejor con el
• No es codigo: no se ejecuta, no tiene logica, es solo texto

Resumen

• Los agentes de codigo necesitan contexto que el README no proporciona
• AGENTS.md es un estandar abierto (Linux Foundation) adoptado por 60,000+ repos
• Un solo archivo funciona con 25+ herramientas (Codex, Claude Code, Cursor, Copilot, etc.)
• Es Markdown puro, sin schema ni sintaxis especial
• Reduce bugs de agentes en 35-55% segun mediciones de la comunidad

---

← Indice | Capitulo 2: Tu Primer AGENTS.md →