AGENTS.md Bien Hecho: Un Aumento del 25% en Precisión — o una Caída del 30%

Augment Code realizó un estudio sistemático sobre archivos AGENTS.md en su monorrepositorio. Los mejores archivos le dieron a su agente de codificación un salto de calidad equivalente a actualizar de Haiku a Opus; los peores empeoraron la salida más que no tener ningún AGENTS.md. El mismo archivo mejoró best_practices en un 25% en una corrección de errores rutinaria y redujo completeness en un 30% en una tarea compleja de características en el mismo módulo. Esto es lo que funciona.

Cómo midieron

Usaron AuggieBench, un conjunto de evaluación interno. Comenzaron con PRs de alta calidad de un repositorio grande que reflejan tareas típicas diarias del agente, configuraron el entorno y el prompt, y pidieron al agente que reprodujera el PR. Compararon la salida con el PR dorado (la versión final después de la revisión de varios ingenieros senior). Los PRs debían estar contenidos dentro de un solo módulo o aplicación, y el alcance debía ser uno donde un AGENTS.md pudiera ayudar de manera plausible. Cada tarea se ejecutó dos veces: con y sin el archivo.

Qué funciona

1. Divulgación progresiva > Cobertura completa

Cubrir casos comunes y flujos de trabajo a un alto nivel; empujar los detalles a archivos de referencia que el agente pueda cargar bajo demanda. Mantener claro el alcance de cada referencia. Archivos de 100–150 líneas con un puñado de documentos de referencia enfocados proporcionaron mejoras del 10–15% en todas las métricas en módulos de tamaño mediano (~100 archivos centrales). Más allá de esa longitud, las ganancias se revirtieron.

2. Flujos de trabajo procedimentales

Un flujo de trabajo numerado de múltiples pasos puede llevar al agente de fallar a terminar. Ejemplo: un flujo de seis pasos para desplegar una nueva integración. Los archivos de conexión faltantes bajaron del 40% al 10%, el agente terminó más rápido, la corrección aumentó un 25%, la completitud un 20%. Mantener el archivo principal conciso y usar archivos de referencia para casos ramificados.

3. Tablas de decisión

Cuando existen dos o tres formas razonables (por ejemplo, React Query vs Zustand para gestión de estado), forzar la elección al inicio con una tabla. Ejemplo:

Pregunta → React Query → Zustand
¿El servidor es la única fuente de datos? ✅
¿Múltiples rutas de código mutan este estado? ✅
¿Necesitas actualizaciones optimistas mezcladas con estado local? ✅

Los PRs en esa área obtuvieron un 25% más en best_practices.

4. Ejemplos cortos de producción

Fragmentos de 3–10 líneas de código real de producción mejoraron la reutilización y la adherencia a patrones. Ejemplo: plantillas de copiar y pegar para primitivas de Redux Toolkit (createSlice con estado inicial tipado, createAsyncThunk con manejo de errores, useAppSelector tipado). code_reuse aumentó un 20%.

5. Reglas específicas del dominio

Todavía importan: el patrón que la mayoría ya asocia con AGENTS.md.