AGENTS.md: La configuración que puede arruinar tu agente

Si has configurado un agente de código, seguramente has creado un AGENTS.md pensando que más contexto significa mejor rendimiento. Yo también lo creí hasta que vi los datos: un AGENTS.md auto-generado puede reducir tu tasa de éxito hasta un 2% mientras dispara los costes un 20%. En este post explico qué dice la investigación sobre estos archivos de configuración y cómo escribir el tuyo para que realmente ayude.

Nota sobre convenciones: Claude Code usa CLAUDE.md, mientras que Cursor, Zed y OpenAI Codex usan AGENTS.md. Los principios de este post aplican a ambos formatos.

¿Por qué los AGENTS.md suelen fallar?

La investigación reciente sobre archivos de contexto revela un patrón contraintuitivo: los archivos auto-generados empeoran el rendimiento de los agentes. Los datos son claros:

Según [1]:

• AGENTS.md generados por LLM reducen tasas de éxito entre 0.5% y 2%
• Aumentan costes de inferencia entre 20% y 23%
• Añaden 2.45-3.92 pasos extra por tarea sin mejorar resultados

El problema no es el concepto, sino la implementación. Los archivos auto-generados tienden a duplicar información que ya existe en la documentación del proyecto, creando ruido en lugar de claridad.

En la mayoría de herramientas, los agentes leen todo el AGENTS.md en cada conversación — aunque el comportamiento exacto varía por cliente; consulta la documentación de tu herramienta — así que cada línea innecesaria diluye las instrucciones que realmente importan.

¿Qué sí funciona en un AGENTS.md?

Los archivos escritos por humanos mejoran el rendimiento en un rango de 2-6% (promedio 4%) en la mayoría de agentes, pero también aumentan costes de inferencia hasta 19%. Nota importante: Claude Code muestra mejoras marginales pero no consistentemente superiores a otros agentes según [1]. Es crucial que sigan el framework WHY-WHAT-HOW para justificar este trade-off:

El WHY: Propósito y arquitectura

Explica por qué existe tu proyecto y cómo se relacionan los componentes principales. No lista directorios, sino que da contexto arquitectónico:

// ❌ Malo: listado de directorios
// src/
//   components/
//   services/
//   utils/

// ✅ Bueno: contexto arquitectónico
// This is a multi-tenant SaaS platform where:
// - Each tenant has isolated data (tenant_id scoping)
// - Background jobs handle document processing
// - Real-time updates use WebSockets for collaboration

El WHAT: Stack y estructura específica

Documenta tu stack tecnológico y decisiones no obvias. Esto es crítico en monorepos:

# Tech stack que el agente necesita conocer
Runtime: Bun
Database: PostgreSQL with Drizzle ORM
Testing: Vitest (not Jest)
Linting: Biome (not ESLint/Prettier)
Deployment: Render with Docker

El HOW: Herramientas y verificación

Incluye comandos de build, test y verificación. Mencionar las herramientas específicas aumenta dramáticamente su uso por el agente según [1]:

# Build & test workflow
bun install           # Never use npm
bun run build         # Builds all packages
bun test              # Runs Vitest across monorepo
bun run typecheck     # TypeScript validation

¿Qué NO incluir en tu AGENTS.md?

Overviews detallados de código

Los agentes pueden descubrir la estructura por sí mismos:

Incluir	No incluir
”auth/ maneja autenticación JWT"	"auth/controllers/, auth/models/, auth/views/"
"Background jobs en workers/"	"workers/email.js, workers/pdf.js, workers/…”
Propósito de cada módulo	Estructura detallada de archivos

Guidelines de estilo de código

Usa linters y formatters en lugar de instrucciones. Son más rápidos, baratos y deterministas. Si tienes Biome configurado, no necesitas explicar el estilo en AGENTS.md.

Instrucciones específicas de tarea

Como AGENTS.md va en cada sesión, solo incluye instrucciones universales. Las específicas diluyen el foco:

❌ "Para debugging de WebSockets, revisar logs en /tmp/socket.log"
✅ "Logs de aplicación en logs/ directory"

❌ "Al actualizar schema, correr migrations en staging primero"
✅ "Database changes require migrations (see docs/database.md)"

¿Cómo estructurar AGENTS.md para máximo impacto?

Mantenerlo corto

El consenso general es menos de 300 líneas. HumanLayer mantiene el suyo bajo 60 líneas. Cada línea va en cada sesión - haz que cuente.

Disclosure progresivo

No pongas todo en AGENTS.md. Crea archivos específicos en agent_docs/:

Nota: el comportamiento varía por herramienta. Algunos clientes abren los archivos referenciados automáticamente; otros requieren que el agente los solicite explícitamente o que lo indiques en el prompt.

# En AGENTS.md (referencias, no contenido completo)
## Documentation Structure
- `agent_docs/database.md` - Schema and migration workflow
- `agent_docs/testing.md` - Test setup and mocking patterns
- `agent_docs/deployment.md` - Environment config (sin credenciales reales; usar .env.example)

## Quick Start
bun install && bun dev

Apuntadores en lugar de copias

Referencia locations file:line en lugar de code snippets incrustados que se vuelven obsoletos. Cuando sea posible, prefiere referenciar por nombre de función o clase en lugar de número de línea:

❌ Copiar 20 líneas de configuración de TypeScript
✅ "TypeScript config in tsconfig.json:12-25"

Errores comunes

El AGENTS.md generado automáticamente

Si usas /init en Claude Code (genera CLAUDE.md) o comandos equivalentes en otras herramientas, estás saboteando el rendimiento. Los datos muestran que reduce éxito y aumenta costes sin beneficio.

Cómo detectarlo: Si tu AGENTS.md tiene listings extensos de archivos o documentación que duplica READMEs existentes.

Cómo arreglarlo: Reescribir completamente, enfocándote en las 3-5 cosas que realmente no puede inferir el agente.

Tratar AGENTS.md como sustituto de linter

Poner reglas de estilo en AGENTS.md es mandar un LLM a hacer trabajo de linter.

Cómo detectarlo: Instrucciones como “usar single quotes”, “no usar var”, “preferir arrow functions”.

Cómo arreglarlo: Configurar Biome/ESLint y remover todas las reglas de estilo del AGENTS.md.

Instrucciones contradictorias con herramientas

Si tu AGENTS.md dice “usar npm” pero tu package.json tiene lockfiles de bun, crea confusión.

Cómo detectarlo: Verificar que comandos en AGENTS.md coincidan con herramientas en package.json/composer.json/requirements.txt.

El archivo de contexto inflado

Incluir información que el agente puede descubrir navegando el código base.

Cómo detectarlo: Si tu AGENTS.md tiene más de 300 líneas.

Cómo arreglarlo: Reducir a lo esencial, mover detalles a archivos separados en agent_docs/.

Checklist de implementación

• AGENTS.md escrito manualmente (nunca auto-generado)
• Menos de 300 líneas total
• Incluye WHAT (stack), WHY (propósito), HOW (comandos)
• No duplica información disponible en documentación existente
• Comandos de build/test/verificación especificados
• Usa disclosure progresivo con archivos agent_docs/ para detalles
• Todas las herramientas mencionadas coinciden con configuración real
• Sin guidelines de estilo (usa linters en su lugar; sí incluye convenciones arquitectónicas que el linter no puede verificar)
• Instrucciones universales solamente (no específicas de tarea)

Fuentes

1. Research on Context Files for Code Agents — ArXiv — datos de rendimiento y costes de archivos de contexto auto-generados vs escritos por humanos.
2. Writing a good CLAUDE.md — HumanLayer — framework WHY/WHAT/HOW y estrategias de disclosure progresivo.

Preguntas Frecuentes

¿Qué pasa si mi AGENTS.md tiene más de 300 líneas?

Cada línea extra diluye las instrucciones importantes. Los LLMs tienen límites prácticos de instrucciones seguibles, y Claude Code ya incluye instrucciones internas significativas en cada sesión. Tu AGENTS.md debe usar el espacio restante sabiamente, priorizando información que el agente no puede inferir del código base.

¿Debo incluir ejemplos de código en AGENTS.md?

No. Prefiere referencias file:line que apunten a código real en tu base. Los code snippets en AGENTS.md se vuelven obsoletos y ocupan espacio valioso. Si necesitas mostrar patrones, crea archivos separados en agent_docs/ con ejemplos completos.

¿Qué herramientas mencionar en la sección HOW?

Solo herramientas no estándar o no obvias. Si usas npm, no lo menciones - es el default. Si usas bun, uv, o poetry, definitivamente inclúyelo. Mencionar las herramientas específicas aumenta dramáticamente su uso por el agente según [1].

¿Cómo sé si mi AGENTS.md está funcionando?

Mide la tasa de éxito en tareas repetitivas y el número de pasos que toma completarlas. Un AGENTS.md efectivo debería reducir pasos innecesarios (como usar herramientas incorrectas) sin aumentar significativamente el tiempo total de las tareas.

¿Puedo tener diferentes AGENTS.md para diferentes proyectos en un monorepo?

Técnicamente sí, pero el comportamiento varía por herramienta — Claude Code lee desde el directorio actual hacia arriba; otras herramientas pueden tener diferente comportamiento. Si tienes necesidades muy diferentes por proyecto, considera usar disclosure progresivo: un AGENTS.md root que referencie projects/api/agent_docs/ y projects/frontend/agent_docs/ para contexto específico.