Cómo escribir un AGENTS.md que realmente ayude a tu agente de codificación de IA

Si has usado un agente de codificación de IA en un proyecto real, probablemente hayas llegado al momento en que ejecuta el comando de prueba equivocado, ignora tu formateador o reinventa un helper que ya tienes. La solución no suele ser un modelo más listo — es darle al agente el contexto específico del proyecto que no puede inferir. Para eso sirve un archivo AGENTS.md.

Qué es AGENTS.md

AGENTS.md es un formato Markdown simple y abierto que da a los agentes de codificación un lugar predecible donde encontrar el contexto y las instrucciones del proyecto. Empezó como una colaboración entre OpenAI Codex, Amp, Google Jules, Cursor y Factory, y ahora está administrado por la Agentic AI Foundation bajo la Linux Foundation. Más de 25 herramientas lo leen — incluyendo Codex, Cursor, VS Code, GitHub Copilot, Aider, Windsurf, JetBrains Junie, Zed y goose — y aparece en más de 60.000 repositorios de código abierto.

Piénsalo como un README escrito para el agente en lugar de para un humano: el README explica tu proyecto a un nuevo colaborador; AGENTS.md le dice al agente las cosas que de otro modo adivinaría mal. (Los usuarios de Claude Code reconocerán CLAUDE.md como el equivalente; muchos equipos mantienen ambos, o enlazan simbólicamente uno con el otro).

Dónde va

Pon AGENTS.md en la raíz del repositorio. En un monorepo, añade archivos anidados dentro de cada paquete — los agentes leen el archivo más cercano en el árbol de directorios, así que un packages/api/AGENTS.md tiene prioridad sobre el de la raíz cuando el agente trabaja en esa carpeta. Esto permite que un servicio en Python y un frontend en TypeScript reciban cada uno instrucciones a medida.

Qué poner en él

El formato es simplemente Markdown — usa los encabezados que quieras. Las secciones comúnmente útiles incluyen:

• Comandos de compilación y prueba — los comandos exactos, no aproximaciones
• Estilo de código — formateador, linter y cualquier convención que un linter no detecte
• Instrucciones de prueba — cómo ejecutar una sola prueba, qué debe pasar antes de dar un cambio por terminado
• Consideraciones de seguridad — archivos u operaciones que nunca tocar
• Convenciones de commit / PR — formato de mensaje, nomenclatura de ramas
• Pasos de despliegue — solo si se espera que el agente los toque

Aquí tienes un ejemplo mínimo y de alta señal:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

Fíjate en lo que no está ahí: ninguna lección de arquitectura, ninguna repetición de la estructura de carpetas, ningún "esta es una aplicación web moderna construida con buenas prácticas." Eso es deliberado.

Más corto suele ser mejor

Hay una tentación de pedirle al agente que te genere un AGENTS.md gigante. Resístete. Un estudio de la ETH Zúrich de 2026, reportado por InfoQ, midió el impacto real de estos archivos y descubrió que el efecto es marginal y mixto. Los archivos de contexto generados por LLM en realidad redujeron las tasas de éxito de las tareas en torno a un 3% de media, a la vez que elevaban los costes de inferencia en más de un 20%. Los archivos escritos por humanos ayudaron de forma modesta — en torno a un 4% de ganancia en el éxito — pero aun así empujaban a los agentes a dar más pasos, aumentando el coste hasta ~19%.

El mecanismo es instructivo: los agentes siguen diligentemente lo que diga el archivo, así que un documento extenso les dice que ejecuten pruebas extra, lean más archivos y realicen comprobaciones de calidad que no eran necesarias para la tarea en cuestión. La recomendación de los investigadores: sáltate por completo los archivos de contexto autogenerados, y limita las instrucciones escritas por humanos a detalles no inferibles — las herramientas específicas y los comandos personalizados que el agente genuinamente no puede descubrir por sí mismo.

En otras palabras, cada línea debería ganarse su lugar evitando un error concreto que realmente has visto cometer al agente.

Un flujo de trabajo que funciona

1. Empieza vacío. No escribas AGENTS.md hasta que hayas visto al agente equivocarse en algo.
2. Añade el arreglo, no la teoría. Cuando ejecute el comando de prueba equivocado, añade el correcto. Cuando reformatee un archivo a su manera y el linter se queje, añade la regla.
3. Mantenlo ajustado. Si una línea solo repite lo que el agente podría leer de package.json o de los nombres de las carpetas, bórrala.
4. Usa el anidamiento para monorepos para que el archivo de cada paquete se mantenga pequeño.
5. Reléelo cada mes. Las instrucciones obsoletas son peores que ninguna — un agente que sigue un comando de compilación desactualizado falla con total seguridad.

Los mejores archivos AGENTS.md se leen como una escueta chuleta de incorporación para ese único compañero de equipo que nunca olvida pero que tampoco infiere nunca. Anota las cosas que no puede adivinar, y nada más.