Hasta no hace mucho hemos trabajado en desarrollo con IA mediante instrucciones, lanzando prompts, uno a uno, explicando en cada prompt las mismas reglas una y otra vez, incluíamos notas en el README y alguna convención oral del equipo. Eso funciona mientras el modelo responde en una caja de chat. En cuanto pasamos a agentes que leen código, ejecutan comandos, editan archivos y validan cambios, ese enfoque se queda corto. Si todavía hoy, sigues trabajando prompt a prompt, entonces te conviene conocer qué es el archivo AGENTS.md: un documento pensado para dar contexto operativo estable a un agente dentro de un repositorio. (GitHub)
El archivo AGENTS.md no es “más documentación”, sino un contrato de trabajo para agentes de IA. Sirve para decirles cómo está organizado el proyecto, qué comandos importan, qué restricciones deben respetar y cómo validar que un cambio está realmente terminado. Bien usado, reduce ambigüedad, baja el número de iteraciones tontas y convierte a un agente de IA en algo más predecible.
Qué es exactamente AGENTS.md
La definición más útil es también la más sobria: AGENTS.md es un formato abierto y simple para guiar agentes de programación. El propio proyecto agentsmd/agents.md lo presenta como un “README para agentes”: un lugar predecible donde poner contexto e instrucciones para que un agente de IA entienda cómo trabajar en tu proyecto.
Esa idea importa porque los agentes no fallan solo por “no saber programar”. Muchas veces fallan por no saber cómo trabajamos en nuestro repositorio. No conocen si, por ejemplo, usamos mvn o mvnw, qué suite hay que ejecutar antes de dar una tarea por cerrada, dónde viven los contratos públicos, qué carpetas no deben tocar o qué criterios usamos para aceptar un cambio. AGENTS.md existe para capturar justo ese conocimiento operativo.
No hablamos, además, de un estándar puramente teórico. OpenAI lo documenta para Codex y GitHub lo soporta para Copilot Coding Agent. En paralelo, otros productos del ecosistema están resolviendo el mismo problema con documentos parecidos, aunque no siempre con el mismo nombre. Claude Code, por ejemplo, trabaja oficialmente con CLAUDE.md y con su sistema de memoria, no con AGENTS.md. Conviene entender esta distinción desde el principio para no mezclar formatos ni promesas de compatibilidad que hoy no son universales.
Qué hace el archivo AGENTS.md en la práctica
AGENTS.md le da al agente tres cosas que un prompt ad-hoc rara vez le da bien a la vez:
- Contexto persistente, porque no depende de que recordemos repetir siempre lo mismo.
- Reglas de ejecución, porque puede explicitar herramientas, comandos y límites.
- Y criterios de validación, porque puede dejar claro qué significa “hecho” en ese repositorio. (OpenAI Developers)
Eso cambia bastante la calidad del trabajo delegado. Un agente sin guía tiende a improvisar: explora de más, asume convenciones incorrectas o propone cambios incompletos. Un agente con un AGENTS.md razonable empieza con un marco: sabe cómo orientarse, qué camino seguir y cómo comprobar que no está rompiendo nada. No elimina los errores, pero sí quita una parte importante de los errores evitables.
En OpenAI Codex, esta idea está muy formalizada.
- Codex lee los archivos
AGENTS.mdantes de empezar a trabajar y construye una cadena de instrucciones combinando guía global y guía específica del proyecto. - GitHub Copilot, por su parte, usa
AGENTS.mdcomo instrucciones de agente para su coding agent, y resuelve conflictos usando el archivo más cercano en el árbol de directorios.
No es exactamente el mismo mecanismo, pero el propósito es el mismo: que el agente no empiece “en frío”.
Para qué se usa
El primer uso es el más obvio: onboarding técnico del agente. Igual que una persona nueva necesita saber cómo arrancar el proyecto, dónde están los tests y qué convenciones mandan, un agente también necesita esa base. El valor de AGENTS.md está en que ese onboarding queda codificado en el repo y no escondido en prompts efímeros o en la cabeza del equipo.
El segundo uso es controlar el radio de acción. Hay repositorios donde el problema no es que el agente haga poco, sino que haga demasiado: tocar módulos que no debía, usar dependencias nuevas sin criterio, saltarse pasos de validación o editar ficheros sensibles. Un buen AGENTS.md no solo orienta; también acota. Y esa parte de guardrails suele ser más importante que la parte descriptiva.
El tercer uso, quizá el más infravalorado, es estandarizar entrega. Si dejamos escrito qué comandos debe ejecutar, qué artefactos debe actualizar y qué evidencias debe devolver, pasamos de “haz el cambio” a “haz el cambio de una forma que podamos revisar”. Esa diferencia es la que separa a un agente simpático de un agente integrable en un flujo real de ingeniería. (The GitHub Blog)
Qué no es el archivo AGENTS.md
No es un sustituto del README.md. El README sigue siendo para humanos: instalación, propósito del proyecto, documentación pública, arquitectura de alto nivel. AGENTS.md cumple otra función: decirle al agente cómo comportarse dentro de ese contexto. Muchas veces ambos se solapan, pero no conviene mezclarlo todo en un mismo documento. El README explica el proyecto; AGENTS.md explica cómo trabajar sobre él.
Tampoco es una política de seguridad fuerte por sí misma. Que algo esté escrito en AGENTS.md no lo convierte en enforcement técnico. En Claude, por ejemplo, la propia documentación recuerda que CLAUDE.md es contexto, no garantía estricta de cumplimiento. Esa idea aplica igual aquí: estas guías mejoran adherencia, pero el control real sigue dependiendo de permisos, sandboxing, revisiones y validaciones automáticas.
Y no es un sitio para volcar todo lo que sabemos del proyecto. Si intentamos meter arquitectura completa, runbooks, decisiones históricas y veinte excepciones, el archivo deja de funcionar. El principio correcto es otro: poca información, pero muy accionable. Lo que más ayuda a decidir y ejecutar debe estar arriba; lo que sea accesorio debería vivir en documentación aparte. OpenAI, de hecho, limita el tamaño combinado que Codex usa por defecto para estas instrucciones.
Cómo descubre un agente el archivo
Aquí conviene separar herramientas, porque no todas descubren AGENTS.md igual.
En Codex, el mecanismo es jerárquico. Puede leer una guía global en ~/.codex/AGENTS.md —o una variante temporal AGENTS.override.md— y después combinarla con los AGENTS.md del proyecto desde la raíz hasta el directorio de trabajo actual. Los archivos más cercanos al contexto concreto pesan más porque aparecen más tarde en la cadena combinada. Además, Codex ignora archivos vacíos y deja de añadir instrucciones cuando alcanza el límite de bytes configurado, que por defecto es 32 KiB.
En GitHub Copilot, la lógica documentada para el coding agent es más simple de explicar: puedes tener uno o varios AGENTS.md en cualquier lugar del repositorio y, cuando Copilot trabaja, el más cercano en el árbol de directorios tiene prioridad sobre otros archivos de instrucciones de agente. GitHub también deja convivir otros mecanismos de instrucciones, como .github/copilot-instructions.md y los ficheros path-specific dentro de .github/instructions/.
En VS Code hay un matiz importante si trabajamos con Copilot: la documentación avisa de que el soporte de AGENTS.md fuera de la raíz del workspace está desactivado por defecto. No es un detalle menor. Significa que, si pensamos en instrucciones anidadas por subdirectorio, debemos revisar bien qué alcance tiene nuestro workspace y no asumir que cualquier archivo intermedio va a descubrirse automáticamente en todas las configuraciones.
Qué debería contener un buen AGENTS.md
Nos funciona pensar este archivo como un documento de ejecución, no de marketing. Lo esencial suele caber en cinco bloques.
- El primero es orientación del repositorio. Aquí van dos o tres notas sobre estructura, puntos de entrada y decisiones que ayudan a no explorar a ciegas. El objetivo no es describir toda la arquitectura, sino ahorrar búsquedas inútiles al agente. (GitHub)
- El segundo es entorno de desarrollo. Qué gestor de paquetes usar, cómo arrancar, cómo navegar por un monorepo, qué dependencias no deben tocarse y qué atajos son fiables. El ejemplo oficial de
agents.mdva justo por ahí: comandos para encontrar paquetes, instalar dependencias y levantar un proyecto concreto. (GitHub) - El tercero es validación. Qué tests ejecutar, qué linters pasar, qué checks mínimos no puede saltarse. Esto suele dar más retorno que cualquier consejo estilístico, porque obliga al agente a cerrar el bucle de cambio y verificación. (GitHub)
- El cuarto es guardrails. Qué carpetas no tocar, cuándo pedir confirmación, qué secretos no leer, cuándo evitar dependencias nuevas, qué ramas o artefactos no modificar. Este bloque es especialmente valioso cuando el agente puede ejecutar herramientas o comandos.
- El quinto es definición de entrega. Qué debe actualizar además del código, cómo documentar cambios públicos, qué formato esperamos en el resumen final, o qué evidencias debe dejar. Esto conecta el trabajo del agente con el criterio de revisión del equipo. (The GitHub Blog)
Ejemplo base de AGENTS.md
Este sería un punto de partida razonable para muchos repositorios. No pretende ser universal; pretende ser útil.
# AGENTS.md ## Contexto del repositorio - Esta aplicación es una API Node.js + TypeScript. - El código de negocio vive en `src/`. - Los contratos HTTP públicos están en `src/contracts/`. - La documentación funcional vive en `docs/`. ## Entorno de trabajo - Usa `pnpm`, no `npm`. - Antes de tocar código, revisa `package.json` y `pnpm-workspace.yaml`. - No añadas dependencias de producción sin justificarlo en el resumen final. ## Reglas de implementación - Haz cambios pequeños y localizados. - Mantén compatibilidad con los contratos existentes salvo que la tarea diga lo contrario. - No renombres archivos o símbolos públicos sin revisar usos. ## Validación - Ejecuta `pnpm lint`. - Ejecuta `pnpm test`. - Si cambias contratos o DTOs, ejecuta también `pnpm test:contracts`. ## Guardrails - No leas ni modifiques `.env`, `.env.*` o `secrets/**`. - No cambies ficheros de CI salvo que la tarea lo pida. - Si necesitas migración de datos o dependencia nueva, deténte y pide confirmación. ## Entrega - Resume qué has cambiado, qué riesgos quedan y qué comandos has ejecutado. - Si cambias comportamiento público, actualiza `docs/`.
La estructura anterior encaja bien con lo que vemos en la documentación y en los ejemplos oficiales: instrucciones breves, operativas y comprobables. Lo importante no es copiarla tal cual, sino escribir algo que un agente pueda ejecutar sin interpretar demasiado. (GitHub)
Configuración en Codex con VS Code
Si trabajamos con Codex, hay dos niveles de configuración que conviene separar: la guía persistente del agente y el entorno desde el que vamos a usarlo.
La guía persistente puede vivir a nivel global en ~/.codex/AGENTS.md y a nivel de proyecto en AGENTS.md dentro del repositorio. Codex carga primero la guía global y luego la del proyecto, recorriendo desde la raíz hasta el directorio actual. Ese diseño permite tener acuerdos generales —por ejemplo, “preferimos pnpm”— y luego especificidades por repo o incluso por subdirectorio. (OpenAI Developers)
En VS Code, OpenAI ofrece la extensión de Codex para trabajar side by side en el IDE o delegar tareas a Codex Cloud. La documentación la presenta como la forma de usar Codex desde VS Code, con capacidad para leer, editar y ejecutar código desde el entorno. (OpenAI Developers)
Una configuración mínima y didáctica podría quedar así:
mkdir -p ~/.codex
# ~/.codex/AGENTS.md ## Acuerdos globales - Preferimos `pnpm` para instalar y ejecutar scripts. - Después de cambios en JavaScript o TypeScript, intenta ejecutar tests relevantes. - Pide confirmación antes de añadir dependencias de producción.
# AGENTS.md (en la raíz del repositorio) ## Contexto del proyecto - Proyecto React + TypeScript con Vite. - La UI está en `src/components`. - La lógica de dominio está en `src/features`. ## Validación - Ejecuta `pnpm lint`. - Ejecuta `pnpm test`. - Si cambias rutas, revisa `src/router`. ## Guardrails - No toques `.env*`. - No actualices dependencias sin justificación.
Con esto ya tenemos una capa global y otra por proyecto. Para un equipo pequeño suele ser suficiente. Nuestra recomendación es empezar así antes de complicarlo con demasiados niveles, porque el objetivo inicial no es construir un meta-sistema, sino mejorar la fiabilidad del agente con el menor coste posible. (OpenAI Developers)
Configuración en GitHub Copilot con VS Code
En Copilot hay que distinguir entre instrucciones generales de repositorio y las instrucciones específicas para agentes.
VS Code recomienda usar instrucciones basadas en archivos para la personalización general de Copilot, y además indica que ciertas instrucciones definidas en settings.json para generación de código y tests están deprecadas desde VS Code 1.102 en favor de archivos como .github/copilot-instructions.md o *.instructions.md. También explica el orden de prioridad: instrucciones personales, luego las del repositorio y después las de organización. (Visual Studio Code)
Para agentes, GitHub documenta AGENTS.md como el archivo específico que usa el coding agent. Puede haber varios dentro del repositorio y manda el más cercano en el árbol de directorios. Eso nos deja un patrón bastante limpio: .github/copilot-instructions.md para normas generales de chat y colaboración, y AGENTS.md para decirle al agente cómo trabajar de forma autónoma. (GitHub Docs)
Un ejemplo práctico en VS Code podría ser este.
# .github/copilot-instructions.md - Usa TypeScript estricto. - Evita lógica de negocio en componentes. - Prioriza cambios pequeños y fáciles de revisar. - Cuando cambies una API pública, sugiere actualización de documentación.
# AGENTS.md ## Cómo trabajar en este repo - Antes de implementar, localiza tests existentes relacionados con la zona afectada. - Mantén los cambios dentro del módulo objetivo salvo necesidad justificada. - Si faltan tests razonables para el caso tocado, propón añadirlos. ## Validación mínima - Ejecuta `pnpm lint` - Ejecuta `pnpm test` - Si cambias componentes UI, ejecuta `pnpm test:ui` ## Restricciones - No leas secretos ni archivos `.env*` - No modifiques workflows de GitHub Actions salvo petición explícita - No introduzcas dependencias nuevas sin explicarlo
Y, si además queremos configurar un agente personalizado en VS Code para Copilot, GitHub permite crear perfiles .agent.md desde el selector de agentes del chat. Esos perfiles viven en .github/agents, pueden incluir descripción, herramientas y prompts, y permiten seleccionar modelo y herramientas disponibles. Es decir, AGENTS.md y los perfiles .agent.md no compiten: resuelven problemas distintos. El primero instruye al agente dentro del repo; el segundo define un agente personalizado reutilizable dentro del entorno. (GitHub Docs)
¿Y qué pasa con Claude?
Aquí hay que ser precisos. Claude Code no documenta AGENTS.md como su mecanismo principal. Lo que usa oficialmente es CLAUDE.md para instrucciones del proyecto y un sistema de memoria con MEMORY.md y archivos temáticos. La documentación explica incluso que CLAUDE.md se carga completo al inicio, mientras que MEMORY.md tiene un límite operativo distinto y actúa como índice de memoria. (Claude API Docs)
Esto no invalida la idea de AGENTS.md; al contrario, refuerza que el problema existe en todo el ecosistema. Lo que cambia es el nombre del contrato y la forma de carga. Por eso conviene pensar en AGENTS.md como una pieza de una familia más amplia de “archivos de instrucciones para agentes”, no como un estándar universal ya cerrado. Hoy OpenAI y GitHub lo soportan directamente; Claude resuelve el mismo caso con otra convención. (OpenAI Developers)
Ejemplo práctico: preparar un repo real para un agente
Imaginemos una API interna que ya funciona, pero donde cada cambio pequeño genera fricción: el agente toca demasiado código, se olvida de los tests de contrato y a veces modifica cosas sensibles de configuración.
La salida fácil sería seguir corrigiendo prompt a prompt. La salida sostenible es capturar el criterio operativo en AGENTS.md. En este caso, el archivo debería dejar claras cuatro cosas: dónde vive el contrato público, qué checks son obligatorios, qué carpetas no tocar y qué debe incluir el resumen final. Ese tipo de información cambia poco y tiene mucho impacto. (OpenAI Developers)
Podríamos escribir algo así:
# AGENTS.md ## Contexto - API Express + TypeScript. - Los endpoints públicos están en `src/http`. - Los esquemas compartidos están en `src/contracts`. - Las decisiones de arquitectura relevantes están en `docs/adr`. ## Antes de cambiar código - Busca tests existentes del módulo afectado. - Revisa si el cambio toca contrato HTTP o solo implementación interna. - Limita el cambio al módulo objetivo. ## Validación obligatoria - `pnpm lint` - `pnpm test` - `pnpm test:contracts` ## No tocar sin pedir confirmación - `.env*` - `infra/**` - `.github/workflows/**` - migraciones destructivas de base de datos ## Definición de terminado - Explica qué cambiaste. - Lista comandos ejecutados. - Indica si cambió el contrato público. - Si cambió el contrato, actualiza `docs/` o justifica por qué no hacía falta.
Con un archivo así, el agente ya no opera a ciegas. Sigue necesitando buen juicio, pero parte de una base mucho mejor. Y, sobre todo, nosotros pasamos de revisar “todo por si acaso” a revisar desviaciones concretas: si no ejecutó pnpm test:contracts, sabemos que ha incumplido una regla explícita; si tocó infra/**, sabemos que se salió del radio permitido. Ahí es donde AGENTS.md empieza a aportar de verdad. (OpenAI Developers)
Errores habituales al crear AGENTS.md
El error más frecuente es escribir instrucciones demasiado genéricas: “escribe código limpio”, “sigue buenas prácticas”, “haz lo correcto”. Eso suena bien, pero ayuda poco. Los agentes obedecen mejor cuando las reglas son concretas, observables y conectadas con herramientas reales del repo. La documentación de Claude lo formula con claridad para CLAUDE.md: las instrucciones específicas se siguen mejor que las vagas. La misma lección aplica aquí. (Claude API Docs)
El segundo error es meter normas que no podemos validar. Si decimos “siempre optimiza el rendimiento” pero no damos una señal operativa, el agente improvisará. En cambio, si decimos “ejecuta este benchmark cuando toques el parser”, ya hemos convertido una intención difusa en un paso ejecutable.
El tercero es usar AGENTS.md para suplir permisos que deberían estar en otra capa. Las instrucciones ayudan, pero no reemplazan ni sandbox ni control de herramientas ni revisión humana. Si algo de verdad no debe ocurrir, tiene que estar respaldado por configuración del entorno, no solo por una frase en Markdown.
Recomendación de adopción
Yo no empezaría por un documento enorme. Empezaría por una versión de 20 a 40 líneas con cuatro bloques: contexto mínimo, comandos de validación, guardrails y definición de entrega. Con eso ya suele mejorar bastante la calidad del trabajo de un agente. Después, solo añadiría reglas nuevas cuando hayamos visto un fallo repetido o una necesidad clara de coordinación. (OpenAI Developers)
También separaría responsabilidades: instrucciones generales del repo en .github/copilot-instructions.md si trabajamos con Copilot, reglas de comportamiento autónomo en AGENTS.md, y permisos o restricciones duras en la configuración propia de la herramienta. Esa separación reduce mezcla conceptual y hace más mantenible el sistema.
La idea de fondo es bastante simple. Un agente funciona mejor cuando el repositorio le habla en el lenguaje de la entrega: qué tocar, qué no tocar, cómo validar y cómo cerrar el trabajo. AGENTS.md es, hoy, una de las formas más directas de codificar ese lenguaje en el propio proyecto. (GitHub)
Conslusión sobre el archivo AGENTS.md
Si tuviéramos que resumirlo en una sola frase, diríamos esto: AGENTS.md es el punto donde un repositorio deja de ser solo código y pasa a ser también un entorno operable por agentes.
No hace magia. No sustituye revisión, ni permisos, ni criterio técnico. Pero sí pone orden en algo que, sin este tipo de archivos, acaba viviendo en prompts repetidos, decisiones implícitas y fricción innecesaria. Y eso, para cualquier equipo que quiera trabajar en serio con agentes de IA sobre código real, ya es bastante. (GitHub)