AGENTS.md: Por qué los humanos deben escribir el contexto de los agentes (y no la IA)
El estudio de la ETH Zurich muestra que los agentes que escriben sus propios archivos de contexto reducen el rendimiento en un 3% y aumentan los costos en un 20%. Mira la plantilla probada de Autenticare.
Fabiano Brito
CTO, Autenticare
AGENTS.md al propio LLM parece eficiente, pero cuesta muy caro en previsibilidad. Datos recientes de la ETH Zurich (Gloaguen et al.) lo demuestran: un archivo de contexto mantenido rigurosamente por humanos supera a la autogeneración en rendimiento y economía de tokens.
La orquestación de agentes autónomos en repositorios complejos exige reglas claras. Cuando sueltas a los agentes en el código, necesitan un mapa geográfico del proyecto, límites arquitectónicos y antipatrones locales. La solución más común para esto en la comunidad es el archivo AGENTS.md.
Pero, ¿quién debería escribir este archivo?
Muchos equipos automatizan la creación del contexto a través de LLMs (“lee este repositorio y resume las reglas”). Sin embargo, la investigación y nuestra experiencia práctica en Autenticare muestran que esto es un fallo arquitectónico.
El Costo de la Autogeneración
tasa de éxito en resolución
aumento en consumo de tokens
modelo ideal probado
Según el reciente estudio de la ETH Zurich, permitir que los agentes infieran y documenten por sí mismos las reglas del proyecto conduce a una disminución del 3% en el éxito de la ejecución de tareas y a un aumento del 20% en los costos.
La razón es simple: el LLM se centra en “qué” hace el código (lo cual ya es obvio al leer los archivos), pero carece de la intencionalidad de “por qué” se hizo así. Un agente que genera AGENTS.md crea descripciones técnicas vacías en lugar de restricciones de negocio (constraints).
La Plantilla Probada de Autenticare
Define el comportamiento esperado, el tono de voz (como el uso obligatorio de respuestas directas) y los límites de lo que el agente puede o no hacer en el repositorio.
En lugar de describir qué es la carpeta src/, establece DÓNDE deben ir las cosas nuevas (ej: "Nunca crees componentes genéricos fuera de ui/").
La parte más valiosa: enumera las soluciones que parecen correctas pero que han sido prohibidas en tu empresa (ej: "Nunca uses lodash, tenemos helpers nativos").
AGENTS.md es tu contrato con la IA. Si la IA escribe su propio contrato, naturalmente moldea las reglas hacia caminos de menor resistencia, ignorando la deuda técnica a largo plazo.
Para la ingeniería agéntica escalable, escribe el contexto estratégico a mano y deja que el LLM automatice solo la ejecución táctica.
Tu AGENTS.md no es una wiki; es una cerca eléctrica de comportamiento. Trátalo como tal.
Para estructurar la base de tu orquestación de IA con las mejores prácticas de Autenticare, descubre nuestra Fábrica de Agentes. ¿Necesitas ayuda con la gobernanza de tu plataforma? Ponte en contacto con nuestro equipo.