AGENTS.md: el archivo de instrucciones para los agentes de código

AGENTS.md es un archivo Markdown normal, en la raíz de un repositorio, que explica a los agentes de código cómo trabajar en el proyecto: cómo compilarlo, cómo lanzar las pruebas, qué convenciones seguir y qué evitar. Su web oficial lo llama un README para agentes, separado del README escrito para personas. A 23 de octubre de 2026, Codex, Cursor, GitHub Copilot y muchas otras herramientas lo leen, y Claude Code lo lee cuando el proyecto no tiene un CLAUDE.md propio. Esta guía explica qué poner en el archivo, cómo lo encuentra cada herramienta y cómo mantenerlo corto y seguro, a partir de la documentación de cada una leída el 23 de octubre de 2026.

Para qué sirve AGENTS.md

Un agente de código empieza cada sesión sin saber nada de tu proyecto. Sin instrucciones adivina el gestor de paquetes, lanza la orden de pruebas equivocada o reformatea archivos contra tu estilo. AGENTS.md le da un sitio predecible donde mirar. El formato no tiene campos obligatorios: es Markdown corriente con los encabezados que tengan sentido. La web agents.md indica que los agentes intentarán ejecutar las órdenes de prueba que pongas, así que el archivo no es solo documentación, sino un conjunto de instrucciones que el agente cumple.

El formato lo custodia ahora una fundación dentro de la Linux Foundation, y la web dice que lo usan más de 60.000 proyectos de código abierto. Entre las herramientas compatibles que cita están Codex, Jules, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, el agente de código de GitHub Copilot, Windsurf y Augment Code.

Qué poner en el archivo

La web agents.md propone una descripción del proyecto, las órdenes de compilación y pruebas, las normas de estilo, las instrucciones de pruebas y las consideraciones de seguridad. Los encabezados ayudan en archivos largos, pero uno mínimo puede tener cuatro líneas:

Instalación: pnpm install y después pnpm dev para el servidor de desarrollo.
Pruebas: ejecuta pnpm test antes de cada commit; todas deben pasar.
Estilo: TypeScript en modo estricto, comillas simples, sin punto y coma.
Seguridad: no subas nunca archivos .env ni muestres secretos en los registros.

Escribe las órdenes tal como hay que teclearlas y prefiere reglas concretas («ejecuta pnpm lint») a vagas («mantén el código limpio»). Si los agentes en la terminal te resultan nuevos, nuestra guía sobre cómo usar Claude Code muestra este tipo de archivo en la práctica.

Cómo lo lee cada herramienta

Tabla: cómo cargan AGENTS.md las herramientas de código (documentación oficial, comprobada el 23 de octubre de 2026)

Claude Code tiene un ajuste llamado Project instructions que decide qué archivo manda: por defecto lee CLAUDE.md o, si no existe, AGENTS.md, y también puede leer los dos, solo CLAUDE.md o solo los archivos gestionados. Si quieres una única fuente para todas las herramientas, Anthropic sugiere dejar las reglas en AGENTS.md e importarlo desde CLAUDE.md con una línea que contenga @AGENTS.md. Claude Code no lee AGENTS.local.md, AGENTS.override.md ni una carpeta .agents/. Nuestra comparación de Claude Code y Cursor recoge las demás diferencias entre los dos.

Archivos anidados en un monorepo

Los repositorios grandes pueden tener un AGENTS.md por paquete. La regla de agents.md es sencilla: manda el archivo más cercano al código que se edita, y una instrucción explícita del usuario en el chat está por encima de todo. Codex detalla el mecanismo: lee un archivo por carpeta desde la raíz hasta donde lo lanzaste, en el orden AGENTS.override.md, AGENTS.md y nombres alternativos, y los concatena para que los más cercanos queden al final. GitHub Copilot acepta además un único CLAUDE.md o GEMINI.md en la raíz en lugar de AGENTS.md, y cuando existen instrucciones personales, de repositorio y de organización las usa todas, con prioridad para las personales.

Mantenlo corto

Cada línea gasta contexto en cada petición, y las herramientas ponen límites. Codex deja de leer las instrucciones del proyecto a los 32 KiB por defecto (project_doc_max_bytes). Anthropic recomienda que cada CLAUDE.md tenga menos de 200 líneas, y Cursor sugiere reglas de menos de 500 líneas. Lleva el material de consulta largo a documentos aparte y, en Claude Code, usa archivos por rutas en .claude/rules/ para que una regla solo se cargue cuando el agente toque los archivos que le corresponden. Para comprobar qué ha cargado Codex, pídele que resuma sus instrucciones actuales.

Seguridad: un archivo de instrucciones es código

Los agentes obedecen AGENTS.md, así que trata sus cambios como los de un script de compilación: revísalos en las pull requests. No pongas nunca claves de API, contraseñas ni tokens, porque el archivo se sube al repositorio y se envía al modelo en cada tarea. Ten cuidado con los repositorios que no son de confianza: un AGENTS.md malicioso es una inyección de prompts servida en bandeja, y un agente con acceso a la terminal puede ejecutar las órdenes que contenga. La misma cautela vale para las herramientas conectadas mediante MCP. Para ver qué agentes merecen tu confianza con el código, consulta nuestra guía de asistentes para programar.