AGENTS.md - un formato abierto para agentes de codificación con IA

 (agents.md)
35 puntos por GN⁺ 2025-08-21 | 1 comentarios | Compartir por WhatsApp
  • AGENTS.md complementa a README y funciona como un archivo dedicado que contiene el contexto y las instrucciones que necesita un agente de codificación con IA al trabajar en un proyecto
  • Ya se usa en más de 20,000 proyectos de código abierto, organizando información como build/test/estilo de código que no es necesaria para las personas, pero sí importante para los agentes
  • Proporciona instrucciones específicas para agentes en una ubicación clara y predecible, manteniendo README conciso y al mismo tiempo mejorando la eficiencia de la colaboración
  • Un solo AGENTS.md es compatible con distintos agentes y herramientas, y en monorepos grandes se pueden usar AGENTS.md individuales por subproyecto
  • Un estándar abierto creado con la colaboración de varios ecosistemas, como OpenAI Codex, Cursor y Google Jules

Why AGENTS.md?

  • README.md es documentación para personas, y ofrece inicio rápido, descripción del proyecto y lineamientos de contribución
  • AGENTS.md es un documento auxiliar para agentes que incluye contexto detallado como reglas de build/test/código sin volver complejo el README
  • Razones para tenerlo como archivo separado
    • Ofrece a los agentes una ubicación predecible para las instrucciones que deben consultar
    • README se mantiene conciso y centrado en contribuyentes humanos
    • Proporciona instrucciones precisas específicas para agentes que complementan la documentación existente
  • Adopta una denominación de estándar abierto que cualquiera puede usar, en lugar de un formato propietario
  • Con un solo AGENTS.md, es compatible con varios agentes de codificación con IA y herramientas

How to use AGENTS.md?

  • 1. Crear el archivo AGENTS.md
    • Colocarlo en la raíz del repositorio (muchos agentes admiten su creación automática)
  • 2. Escribir los apartados principales
    • Resumen del proyecto
    • Comandos de build y test
    • Lineamientos de estilo de código
    • Cómo ejecutar pruebas
    • Consideraciones de seguridad
  • 3. Incluir instrucciones adicionales
    • Reglas de commit/PR, precauciones de seguridad, datasets grandes, pasos de despliegue y otros puntos que el equipo quiera transmitir
  • 4. Soporte para monorepos
    • Se puede colocar un AGENTS.md para cada paquete
    • El agente lee el archivo más cercano y sigue las instrucciones correspondientes a ese subproyecto
    • Ejemplo: el repositorio de OpenAI tiene 88 archivos AGENTS.md

FAQ

  • Elementos obligatorios: ninguno; se puede usar libremente el formato general de Markdown
  • Si hay conflictos: tiene prioridad el AGENTS.md más cercano, y el prompt explícito del usuario se aplica al final
  • Ejecución automática: el agente puede ejecutar los comandos de prueba indicados en el archivo para intentar corregir errores
  • Posibilidad de actualización: se puede cambiar en cualquier momento; se gestiona como un documento vivo
  • Migración de documentación existente: cambiar el nombre del archivo y mantener compatibilidad con un enlace simbólico
    • mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-08-21
Opiniones en Hacker News

  • En proyectos pequeños, un solo archivo .md puede ser suficiente, pero por experiencia, en proyectos complejos una estructura jerárquica de carpetas con index.md resulta mucho más efectiva
    Una estructura compuesta por index.md y archivos debajo como auth.md o performance.md también es fácil de mantener, y permite que un LLM o un agente extraiga solo el contexto relevante sin gastar tokens innecesariamente
    Los archivos .docs terminan siendo adecuados tanto para humanos como para LLM, y en index.md incluso se puede incluir una guía breve de cada archivo junto con pautas de organización
    Aun así, en lugar del nombre .agents, me parecería mejor algo más intuitivo como .codebots o .context

    • Creo que no hace falta ocultar archivos y directorios importantes
      Especialmente en el caso de la documentación, esconderla solo la vuelve más opaca; no sé si será por tradición, pero no me parece un buen patrón
      Me pregunto si un nombre como robot_docs sería mejor

    • En realidad, como esta información se superpone con lo que les interesa a los contribuidores, creo que lo correcto sería que estuviera en CONTRIBUTING.md

    • Esta estructura se siente como documentación de diseño de software / guía de estilo de código tanto para humanos como para robots
      Yo pongo estos archivos .md dentro de la carpeta docs/, y Claude Code los redacta directamente
      AGENTS.md y CLAUDE.md deberían ser solo para uso de robots, y ya sea que se dividan las secciones con encabezados h2 en un único archivo grande o que se repartan en varios archivos, ambas opciones tienen pros y contras
      También existen formatos de documentación de arquitectura como Arc42 que soportan ambos enfoques
      En lugar de referenciar una sección específica dentro de un Markdown grande, es más fácil y se cometen menos errores si se crea un archivo aparte y se menciona con @
      Cuando hace falta enfocarse en una parte específica, dividirlo en archivos pequeños también le viene mejor a un agente de código
      Los archivos pequeños también son más cómodos al revisar diff/PR

    • También se pueden tener varios archivos AGENTS.md dentro del codebase
      Si el tooling lee tanto el AGENTS.md del directorio actual como el del directorio raíz, la información puede mantenerse cerca del código y convivir con el enfoque que uno quiera

    • Yo también uso una estructura parecida, y me ha dado bastante buen resultado agregar una guía breve por archivo en index.md
      También estoy probando una forma de poner archivos de reglas de comportamiento deseado por directorio, como rules.md
      Por ejemplo, en un directorio donde se juntan varios servicios como realtime-service.ts y queue-service.ts, se deja un rules.md al lado
      Se puede indicar ese archivo de reglas en el prompt para generar cosas nuevas fácilmente; el nombre todavía necesita pensarse mejor

  • Ahora mismo estamos en una etapa de transición en la que hay que escribir guías especiales adicionales, más allá de lo que necesitaría una persona, para que los agentes entiendan el codebase
    Creo que pronto eso ya no hará falta
    Si la documentación de nuestros proyectos estuviera bien hecha desde el principio, todo lo que hoy está en AGENTS.md también podría estar incluido ahí
    Siempre deberíamos escribir documentación pensando en humanos, y la ventaja de los LLM es precisamente que pueden leer lo que escriben los humanos
    Me parece que ese es el enfoque correcto de diseño

    • No solo sirve para entender el codebase, sino también para dejar explícitas reglas de estilo específicas, por ejemplo con qué librería de assert escribir tests, prohibir comentarios o exigir logging estructurado
      De hecho, puede ser todavía más útil en proyectos nuevos que apenas tienen código

    • Espero que se adopten muchas más reglas legibles por máquinas en distintos ámbitos de la sociedad
      Un ejemplo serían la conducción autónoma y las normas de tránsito: incluso señales que para una persona ya son difíciles de interpretar en contexto, como "prohibido girar a la derecha con luz roja, días de clase de 7 a 9", para una máquina son aún más complicadas
      Al final, las autoridades van a tener que cambiar a señales que requieran menos contexto o que sean legibles por máquinas, como códigos QR
      Si eso no pasa, las máquinas van a terminar rompiendo reglas con frecuencia

    • En áreas como la lógica de negocio, creo que seguirá siendo indispensable tener instrucciones especiales para agentes
      Qué se está construyendo, cuál es la intención o cuál es el objetivo final del proyecto son cosas que una máquina no puede deducir si una persona no las explica de forma concreta
      Lo mismo con la arquitectura: como cada persona tiene criterios distintos, ayuda tener la estructura mental ya formada para entender cambios reales, y al final ese es el verdadero cuello de botella

    • En general estoy de acuerdo, pero también surge la tentación de forzar cierta información a incluirse desde un archivo separado, por ejemplo cosas que uno quiere meter siempre en el contexto

    • Si no documentamos las reglas y supuestos que damos por implícitos, el LLM no los puede saber
      Podrá inferir algunas cosas a partir del código, pero nunca al 100%, así que es importante dejar los requisitos por escrito de forma explícita

  • Al final, AGENTS.md cumple el mismo papel que README.md, pero con hype de por medio, y es curioso que gracias a eso la gente realmente esté llenando el contenido
    A la gente le da flojera escribir documentación para otras personas, pero para robots sí se ponen a escribir con ganas; eso me parece interesante
    Se parece a cuando se diseña algo ergonómico pensando en un grupo muy pequeño y al final termina funcionando mejor para todos, como cierto diseño de manija

    • Más bien al revés: como la gente no leía la documentación, nadie tenía motivación para escribirla
      En cambio, un CLAUDE.md para agentes, una vez escrito, pronto lo van a leer 1000 agentes, así que sí dan ganas de redactarlo

    • Igual da la impresión de que bastaría con poner lo mínimo en README.md

    • En la práctica, ni siquiera los agentes leen estos documentos, o si les das unas cuantas instrucciones más, se olvidan de todo

    • La situación actual existe porque la gente está intentando sacar de forma activa a los desarrolladores humanos —incluyéndose a sí mismos— del proceso de desarrollo, y por eso los agentes tienen que contar sí o sí con orientación adecuada
      Porque ha crecido mucho el deseo de eliminar toda participación humana en el desarrollo de software

build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors. Separar este tipo de cosas me provoca de verdad esa sensación de no entender en qué se está convirtiendo el mundo

  • En tono de broma, se menciona que el ambiente actual es puro vibe coding
    Creo que antes también apareció la opinión de que escribir documentación para bots al final no es tan distinto de escribir buena documentación en general

  • Al final, se siente como si solo dijeran "crea un archivo AGENTS.md y rellénalo con magia", y luego te mandaran a otro sitio con un link

  • En mi caso, estoy desarrollando un agente de programación que administra más de 5,000 repositorios
    El estado del agente se guarda dentro de un directorio oculto .agent, e incluye carpetas de configuración por rol del agente e instrucciones claramente definidas para cada rol
    En la carpeta del proyecto pongo una carpeta agents, y divido varios archivos por rol con el formato <Role> <instruction>
    El agente solo lee archivos cuyo rol está definido, y el estado se guarda en una carpeta dot<coding agent name>
    La inicialización se hace con /init y, en lugar de indexar simplemente todo el código del repo, genera un high-level summary de toda la arquitectura y la lógica
    Ese resumen se ofrece en el editor como "ghost comments" que se pueden activar o desactivar, y es metadata que no se commitea al código real
    Cada resumen está conectado con precisión a líneas de código mediante un sistema de mapeo sofisticado
    Cuando al principio usé RAG directamente sobre el código, no obtuve el resultado que quería, así que adopté esta estructura
    Ahora uso un modelo de búsqueda híbrido que combina búsqueda sintáctica rápida basada en AST con exploración semántica (RAG) basada en resúmenes
    Por ejemplo, si preguntas "¿cómo funciona la autenticación de esta app?", la búsqueda sintáctica solo encuentra funciones que contienen palabras como login, pero la búsqueda semántica, a través de los resúmenes, reconstruye narrativamente todo el flujo de autenticación y conecta contenido disperso entre archivos; en ese sentido funciona casi como magia

    • Sumando a eso, se puede construir una jerarquía de resúmenes, ya sea en forma de árbol B o de árbol común
      Es decir, habría un summary por método/clase/módulo, y cada nivel apuntaría a niveles inferiores
      Así, RAG puede profundizar tanto como haga falta según la consulta semántica, y cada paso resume el contenido inferior para reducir la cantidad de información sin perder el significado imprescindible
      Este enfoque es especialmente efectivo cuando el código tiene buenas abstracciones
      Por ejemplo, en una función como add(n1, n2), el nombre por sí solo ya transmite suficiente significado y quizá no hace falta ver la implementación real, pero en funciones del mundo real suele haber varias responsabilidades, como logging o caché, así que según el caso también puede ser necesario meter el código real en el contexto

    • Me gustaría escuchar una explicación más detallada

  • Se siente como si poco a poco estuviéramos empujando a los humanos a documentar bien los proyectos

    • Lo digo medio en broma, pero en realidad sí uso este argumento con el equipo
      Incluso si los LLM no aumentaran muchísimo la productividad, al menos sí están logrando que la documentación mejore bastante

    • "Mission. Fucking. Accomplished." xkcd 810

  • Todavía no estoy convencido de que realmente haya que separar README.md y AGENTS.md

  1. el estilo de redacción (por ejemplo, énfasis en MAYÚSCULAS que en documentos para agentes funciona, pero para humanos resulta incómodo)
  2. concisión vs. exhaustividad (la documentación para agentes debería llevarse solo la información esencial, mientras que la de humanos debería documentarlo todo tanto como sea posible)
  3. diferencia de información necesaria (lo que necesita un LLM y lo que considera importante un humano no siempre coincide)
    Y la razón para no separarlos sería
  4. gestión duplicada (la carga de tener que escribir lo mismo, en esencia, en dos lugares distintos)

  • Siento que README.md ahora sirve más como una especie de página de marketing/landing, mientras que AGENTS.md y CLAUDE.md son donde uno va a buscar el contenido real sobre código, arquitectura y uso

  • Mientras leía los ejemplos pensé exactamente lo mismo: quizá con un solo buen README.md que lo contenga todo ya debería bastar

  • README es para humanos; AGENTS.md y similares son para LLM
    En el readme van las instrucciones de uso/instalación, y en los documentos para agentes se organizan cosas como cómo compilar/probar, decisiones de arquitectura, estándares de código y estructura del repo

  • También hay que considerar el tema de la capacidad de contexto en los LLM
    README.md suele ser largo, así que cuesta meterlo entero en el contexto
    En AGENT.md solo se ponen de forma concisa los comandos clave que el LLM necesita, como tests y build
    Puede haber superposición con el README, pero se quiere evitar mandar una y otra vez al contexto contenido innecesario

  • ¿No se suponía que la promesa de la IA era precisamente que no tuviéramos que obsesionarnos con formatos exactos y que bastaba con escribir las cosas a nuestra manera para que la máquina las entendiera?

    • En la práctica, lo correcto fue estandarizar solo el nombre del archivo, sin imponer ningún formato para el contenido, de modo que cada quien pueda escribirlo como quiera
      AGENTS.md es Markdown estándar, así que puedes usar los encabezados que quieras, y el agente analiza el texto

    • Aun así, cierto grado de estructura y formato sí importa
      Aunque no al nivel exacto de una sintaxis de código

    • Al final, la conclusión es que hay que escribir el contenido con claridad
      Mientras más largo se vuelve un documento, más conviene un enfoque estructurado para poder mantenerlo desde la perspectiva humana

  • Cada agente que uso (Claude Code, Gemini, Aider) tiene un nombre de archivo distinto
    Ojalá se estandarice, pero por ahora acepto el trabajo extra de generar automáticamente varios formatos con ruler
    Sobre todo porque cada agente también consume de forma distinta los archivos de configuración de MCP, así que no creo que la estandarización vaya a llegar tan pronto
    ruler

    • Visto de manera un poco cínica, diría que es un movimiento para crear vendor lock-in
      Parece que las empresas evitan la estandarización porque podría llevar a la comoditización

    • Jules usa AGENTS.md, así que Google parece estar sumándose a este estándar
      Si Gemini Code Assist sigue existiendo, esperaría que también termine soportando AGENTS.md
      En la documentación de Aider no se menciona un nombre de archivo específico; si tienes un link, me gustaría verlo
      Parece que Anthropic es el único que todavía no soporta un nombre de archivo estándar

    • Es una lástima que de verdad haga falta una herramienta como ruler

  • Es un sitio web que se siente raro
    Me da la impresión de que si OpenAI lo hizo, fue para atraer visitantes y posicionarse en marketing
    En la práctica no define un formato, solo el nombre del archivo
    También llama la atención que falte Anthropic/Claude; aunque siempre se puede usar la técnica de symlink para conectar CLAUDE.md con AGENTS.md

    • En realidad lo hizo Sourcegraph y existe desde mayo
      Antes era agent.md, y ahora redirige con 301 a agents.md
      Ver link anterior
      También hay un anuncio oficial
      Parece que recientemente hicieron una alianza con OpenAI
      Curiosamente, al principio era agent.md, pero ahora cambió a agents.md

    • La razón de que Claude no aparezca en la lista es que Claude es el único que todavía no soporta una convención estándar de nombre de archivo