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 es un archivo de contexto que define las reglas, límites arquitectónicos y antipatrones para guiar a los agentes autónomos en repositorios de código complejos. Para las empresas, garantizar que este documento sea redactado por humanos y no autogenerado por IA es fundamental para evitar pérdidas de rendimiento y un incremento del 20% en los costos de tokens.
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.
Preguntas Frecuentes sobre AGENTS.md: Por qué los humanos deben escribir el contexto de los agentes (y no la IA)
¿Cuál es el problema de dejar que la IA genere el archivo AGENTS.md? Dejar que la IA genere el AGENTS.md puede llevar a un rendimiento inferior y costos más altos, ya que la IA tiende a enfocarse en el “qué” hace el código, en lugar del “por qué”, resultando en descripciones técnicas vacías en lugar de restricciones de negocio.
¿Qué debo incluir en el archivo AGENTS.md? El archivo AGENTS.md debe incluir la identidad y el contrato operacional de los agentes, un mapa de arquitectura rígida y un catálogo de anti-patterns locales.
¿Cuál es la importancia del control humano en la creación del AGENTS.md? El control humano en la creación del AGENTS.md garantiza que el contexto estratégico se defina manualmente, permitiendo que la IA automatice solo la ejecución táctica, evitando que ella moldee las reglas para caminos de menor resistencia.
¿Cuáles son los beneficios de un AGENTS.md bien definido? Un AGENTS.md bien definido actúa como una cerca eléctrica comportamental, guiando a los agentes de IA y garantizando que sigan las restricciones de negocio y eviten anti-patterns.