AGENTS.md ganó en las dos tareas que probé. Mi primera medición dijo que había perdido una.

Corrí un agente de código con y sin AGENTS.md, cinco veces cada uno. Ganó en las dos tareas que probé. Mi primer intento de medirlo dijo lo contrario, y ese número estaba mal.

Corrí un agente de código contra la misma tarea, con y sin un archivo AGENTS.md, cinco veces cada uno, y saqué la mediana. AGENTS.md ganó. Más rápido, más barato, y produjo diffs más ajustados, tanto en una tarea ambigua como en una de múltiples archivos.

Eso no fue lo que dijo mi primera pasada. Una corrida por condición, sin medianas, y la tarea más difícil mostró a AGENTS.md corriendo 44% más lento y costando 41% más créditos por el mismo resultado. Números lo suficientemente limpios para encabezar un artículo. También equivocados.

El tiempo real y el conteo de tokens tienen ruido por corrida. Antes de confiar en esa primera pasada, corrí cada condición cuatro veces más y saqué la mediana en vez de la muestra única. La pérdida no sobrevivió. Mi corrida de AGENTS.md en la “tarea difícil” resultó ser la más lenta de cinco, emparejada contra una de las corridas sin AGENTS.md más rápidas. Mala suerte, justo en la dirección que hace un buen titular y una conclusión equivocada.

Acá está el harness, los números reales, y lo que una sola corrida se equivocó.

Lo que armé

Repo: teamxray, una extensión de VS Code que construí. TypeScript, webpack, npm, vscode-test. Estructura lo suficientemente real para probar si un AGENTS.md cambia el comportamiento del agente en trabajo específico del repo.

Dos clones idénticos. Mismo commit. Sin AGENTS.md, sin CLAUDE.md, sin caché. node_modules preinstalado en ambos para que npm install no dominara el tiempo total.

Agente: Copilot CLI en modo no interactivo.

copilot --prompt "$PROMPT" --allow-all-tools --add-dir "$REPO" \
        --no-color --log-dir "$LOGS" --log-level info

Copilot CLI reporta créditos, tokens, y tiempo real al final de cada corrida. Capturé stdout, stderr, diffs de git, y la salida de validación de cada corrida.

Cada condición corrió cinco veces. Reset limpio de git entre corridas, mismo prompt, mismo commit inicial. Reporto las medianas abajo, más el rango completo, porque una corrida es una muestra, no un resultado.

El AGENTS.md de doce líneas:

# AGENTS.md

## Project context
Team X-Ray is a VS Code extension built with TypeScript and webpack.

## Commands
- Install: `npm install`
- Compile (production): `npm run package`
- Compile tests: `npm run compile-tests`
- Lint: `npm run lint`
- Type check: `tsc -p .`

Use npm. Not pnpm. Not yarn.

## Rules
- Source code lives in `src/`. Follow existing directory structure.
- Do not edit files in `dist/`, `out/`, or `node_modules/`.
- Do not modify the `postinstall` script in package.json.
- Do not modify webpack.config.js unless the task requires it.
- Add tests alongside the code they cover.
- Keep changes scoped to the requested task.

## Validation
Before finishing, run `npm run lint` and `npm run compile-tests`.
If a check fails, include the exact command and error.

Tarea 1: agregar una función utilitaria

El prompt: agregar un helper formatDuration(ms) que devuelva "500ms", "1.5s", "1m 5s", "1h 1m 5s". Agregar unit tests. Asegurarse de que el lint y el type check pasen.

Superficie ambigua, ejecución obvia. Cada corrida en ambas condiciones descubrió que src/utils/ existe y que src/core/__tests__/ usa vitest.

Métrica (mediana, n=5)	Sin AGENTS.md	Con AGENTS.md	Delta
Tiempo total	110s	80s	−27%
Créditos de IA	24.2	18.3	−24%
Tokens de subida	600.3k	460.5k	−23%
Tokens de bajada	6.0k	4.6k	−23%
Llamadas a herramientas	18	14	−22%
Líneas agregadas	76	56	−26%
¿Rompió el build?	no (5/5)	no (5/5)	empate

Rango entre las cinco corridas: el tiempo total varió entre 88 y 126s sin AGENTS.md, y entre 69 y 100s con él. Solo una corrida de cada condición cayó en la banda compartida de 88 a 100s. Este resultado se sostuvo.

Las líneas agregadas cuentan la historia más clara. Sin AGENTS.md: 61, 72, 76, 82, 86. Con AGENTS.md: 52, 56, 56, 62, 63. En mi primera corrida, la versión sin AGENTS.md agregó manejo de NaN, protecciones para Infinity, y formato de números negativos que nadie pidió, más seis casos de prueba en vez de cuatro. Ese ejemplo específico fue de una sola corrida, pero la diferencia en el conteo de líneas se sostuvo en las cinco: cada corrida con AGENTS.md produjo un diff más ajustado que todas menos una de las corridas sin AGENTS.md.

Una sola línea del archivo hace ese trabajo: Keep changes scoped to the requested task.

Tarea 2: registrar un nuevo comando de VS Code

El prompt: agregar un comando llamado Team X-Ray: Show Analysis Cache Stats. Registrarlo en package.json bajo contributes.commands y activationEvents. Conectarlo en src/extension.ts siguiendo los patrones existentes.

Multi-archivo. Toca la sección scripts de package.json por proximidad. El AGENTS.md advierte contra modificar el script postinstall y webpack.config.js, ambas trampas al alcance de la mano.

Métrica (mediana, n=5)	Sin AGENTS.md	Con AGENTS.md	Delta
Tiempo total	55s	50s	−9%
Créditos de IA	15.6	14.1	−10%
Tokens de subida	406.1k	335.3k	−17%
Tokens de bajada	2.8k	2.7k	−4%
Llamadas a herramientas	11	10	−9%
Líneas agregadas	9	10	+1
¿postinstall intacto?	sí (5/5)	sí (5/5)	empate
¿webpack.config.js tocado?	no (5/5)	no (5/5)	empate

Una victoria más pequeña que en la tarea 1, y mi comparación original de una sola corrida cayó completamente del lado equivocado. Mi primera corrida sin AGENTS.md terminó en 48s, cerca del extremo rápido de su rango. Mi primera corrida con AGENTS.md terminó en 69s, la más lenta de las cinco. Emparejadas entre sí, eso produjo el titular de “41% peor.” Emparejadas contra sus propias medianas, ambos números son poco notables.

El hallazgo más interesante es el rango, no la mediana. Sin AGENTS.md: 44, 48, 55, 97, 109 segundos. Con AGENTS.md: 45, 46, 50, 52, 69 segundos. La condición sin AGENTS.md tiene una cola larga. La condición con AGENTS.md, en su mayoría, no.

Revisé qué hicieron realmente las dos corridas lentas sin AGENTS.md. Una empezó con “Locate teamxray repo in home” y “Show current directory,” gastando llamadas a herramientas en averiguar dónde estaba antes de tocar un solo archivo. La otra hizo el mismo trabajo de orientación, y después corrió un build completo de producción de webpack con npm run compile al final, sin que nadie lo pidiera. Todas las corridas con AGENTS.md se saltaron ambas cosas. El archivo no solo guió la edición, eliminó la razón de ponerse a buscar contexto desde el principio.

Lo que me hizo cambiar de opinión

AGENTS.md ganó en las dos tareas una vez que lo medí bien. El margen no fue el mismo, y esa diferencia es el hallazgo real.

En la tarea ambigua, AGENTS.md redujo tanto el tiempo como el alcance del cambio. La instrucción “keep changes scoped” eliminó código defensivo que nadie pidió, de forma consistente, en las cinco corridas.

En la tarea bien especificada, la ventaja de la mediana fue más pequeña, entre 9 y 17% dependiendo de la métrica. Pero la cola se redujo mucho más que la mediana. Sin contexto del repo, dos de cinco corridas gastaron tiempo reorientándose o validando de más. Con él, ninguna lo hizo.

Si hubiera publicado el artículo después de una sola corrida de cada una, habría publicado un número que sonaba cierto pero que en realidad era ruido. Ese es el riesgo con cualquier benchmark de agentes que reporta una sola corrida: el tiempo real y el conteo de tokens varían lo suficiente entre corridas como para que una sola comparación apunte en la dirección equivocada con toda la seriedad del mundo.

Qué va en un AGENTS.md

Leí un montón de documentación antes de escribir la versión que probé: el proyecto oficial de AGENTS.md, la guía de AGENTS.md de OpenAI Codex, los docs de reglas de Cursor, el manual de Amp, los docs de memoria de Claude Code, y los docs de reglas de Warp.

Todos coinciden en la forma.

Lo concreto le gana a lo aspiracional. Siempre.

Débil:

Follow best practices.
Make sure tests pass.
Be careful with generated files.

Útil:

Run `npm run lint` after any source change.
Do not edit files in `dist/`, `out/`, or `node_modules/`.
Use existing helpers in `src/utils` before creating new ones.

La versión débil le da al agente puras vibras. La versión útil le da comandos, rutas, y restricciones. Tres líneas cada una. Comportamiento distinto en tiempo de ejecución.

La segunda regla que comparten esos docs: que sea corto.

Cursor recomienda reglas enfocadas de menos de 500 líneas. Claude Code apunta a menos de 200 líneas para CLAUDE.md. La guía de OpenAI Codex menciona un límite de bytes en toda la cadena de instrucciones combinadas, así que los archivos muy grandes pueden truncarse. Si tu AGENTS.md es una pared de texto, las partes que te importan podrían no sobrevivir el viaje.

Mi archivo de doce líneas ya carga un costo fijo en cada llamada: se lee, se parsea, y se razona sobre él en cada turno, sin importar si la tarea lo necesita o no. Un archivo de trescientas líneas carga una versión más grande de ese mismo costo, en cada corrida, sin importar si esa corrida llega a tocar la parte que importaba.

Lo raro va en el archivo

El ejemplo real más fuerte que encontré vive en el repo de OpenAI Codex.

No se queda en “corre los tests.” Tiene reglas de formato específicas para Rust, límites de “nunca agregar ni modificar” alrededor del código del sandbox, indicaciones para usar just test en vez de cargo test directo, consejos de monorepo sobre no sobrecargar los crates principales, y una guía de tamaño de cambios para mantener los diffs revisables.

Esa es la vara.

Si tu repo tiene un comando maldito que todo el mundo sabe que no debe correr, ponlo en AGENTS.md. Si una carpeta es la dueña de los tipos de la API, ponlo en AGENTS.md. Si el agente debería usar npm run pretest && npm test y nunca un npm test a secas, ponlo en AGENTS.md.

El archivo debería responder las preguntas que el agente, de otra forma, aprendería rompiendo algo.

Los archivos AGENTS.md anidados son el patrón para monorepos

Todos los docs que leí sobre monorepos llegan a la misma forma. Archivo raíz general. Archivos de carpeta específicos. Gana el archivo más cercano.

repo/
├── AGENTS.md                    # workspace rules
├── apps/
│   └── web/
│       └── AGENTS.md            # Next.js rules
└── packages/
    └── api/
        └── AGENTS.md            # schema helpers, fixtures

El FAQ de AGENTS.md deja la precedencia explícita: gana el archivo más cercano, y los prompts explícitos del usuario siguen superando al archivo. Esa jerarquía mantiene las instrucciones del repo útiles sin que se vuelvan más importantes que la tarea real.

No crees un árbol anidado porque se ve organizado. Agrega un archivo a nivel de carpeta la primera vez que las reglas de la raíz dejen de ser ciertas dentro de esa carpeta.

AGENTS.md es guía, no cumplimiento forzado

Esta es la parte en la que vale la pena ser honesto, y también es la parte que hace que el estándar importe.

AGENTS.md le puede decir al agente que no haga commit de secretos. No puede garantizar que el agente no lo haga. Le puede decir que corra los tests antes de terminar. No puede forzar que eso pase si algo se rompe antes en la cadena.

Tanto el manual de Amp como los docs de memoria de Claude Code lo dicen sin rodeos: las instrucciones guían el comportamiento, no lo hacen cumplir. Eso es cierto para cualquier archivo de instrucciones, en cualquier herramienta, de cualquier proveedor.

Acá está el argumento real para un estándar compartido. Un equipo que corre tres agentes de código sin uno está manteniendo tres archivos separados con la misma guía del repo, cada uno actualizado por quien se acordó de último, cada uno desincronizándose a su propio ritmo. Un solo AGENTS.md portable y versionado en git significa un solo lugar para arreglar una instrucción equivocada y un solo diff para que cada agente lo recoja apenas se haga merge.

El cumplimiento sigue viviendo donde siempre ha vivido: CI, status checks obligatorios, protección de ramas, escaneo de secretos, exclusiones de contenido, hooks en tu configuración de Copilot cloud agent, y runners en sandbox para trabajo no confiable.

Markdown guía. Los checks deciden. El trabajo de AGENTS.md es hacer que cada agente lea la misma guía, no inventar barreras que Markdown nunca estuvo hecho para dar.

Por qué el formato vive bajo una fundación

La razón por la que corrí este experimento: AGENTS.md seguía apareciendo en cada doc de agentes de código que leía. Codex, Copilot, Cursor, Amp, opencode, Warp, Claude Code, goose. Empresas distintas, modelos de precio distintos, UX distinta. El mismo archivo de instrucciones en la raíz del repo. Claude Code lee CLAUDE.md de forma nativa, pero sus docs de memoria recomiendan un import de una línea con @AGENTS.md o un symlink, para que ambos archivos se mantengan sincronizados desde una sola fuente de verdad.

Ese es un resultado poco común en el espacio de herramientas para agentes, y requiere coordinación deliberada.

AGENTS.md ahora está bajo el cuidado de la Agentic AI Foundation, un proyecto de la Linux Foundation. AAIF también respalda a MCP, goose, y agentgateway, las otras piezas de infraestructura agéntica abierta que la mayoría de agentes de código ya tocan. El desarrollo pasa en público en github.com/agentsmd/agents.md.

Si tu equipo está eligiendo herramientas de agentes este trimestre, AGENTS.md te da contexto de repo portable. Tus instrucciones viajan con tu repo, así que cambiar de agente no significa reescribirlas.

Lo que de verdad haría

Si estuviera agregando AGENTS.md a un repo mañana con estos números sobre la mesa:

Empieza con la versión de doce líneas. Gestor de paquetes, comandos clave, límite de archivos generados, “keep changes scoped.” Publícala.
Corre una tarea pequeña con el agente. Fíjate dónde adivina mal. Convierte cada adivinanza en una línea del archivo.
Agrega un AGENTS.md a nivel de carpeta solo cuando las reglas de la raíz dejen de ser ciertas dentro de esa carpeta. No antes.
Mueve el cumplimiento al CI, no al Markdown. Deja que AGENTS.md guíe. Deja que los checks decidan.
Cada vez que un agente produce un mal PR, pregúntate si AGENTS.md lo pudo haber evitado. Si la respuesta es sí, actualiza el archivo.

No optimices para el costo promedio de tokens. Optimiza para la cola. Las corridas donde el agente, de otra forma, gastaría una hora, inventaría un helper, o tocaría un archivo que no debería.

Ahí es donde AGENTS.md se paga solo.

Todas las mediciones se capturaron con GitHub Copilot CLI en modo no interactivo el 3 de julio de 2026, contra clones locales de AndreaGriffiths11/teamxray. Cada una de las cuatro condiciones (dos tareas × con/sin AGENTS.md) corrió cinco veces en total desde un reset limpio de git; los valores reportados son medianas, con el rango completo por corrida anotado en el texto. Los “AI Credits” son lo que reporta Copilot CLI; bajo la facturación por uso de Copilot, se traducen a GitHub AI Credits a las tarifas publicadas del proveedor del modelo. Fuentes: agents.md, openai/codex AGENTS.md, guía de AGENTS.md de OpenAI Codex, docs de reglas de Cursor, manual de Amp, docs de memoria de Claude Code, docs de reglas de Warp, instrucciones personalizadas de repositorio de GitHub Copilot.