)
Última actualización: 5 de noviembre, 2026
¿Qué es AGENTS.md? AGENTS.md es un archivo Markdown sencillo, normalmente en la raíz del repositorio, que explica a los agentes de código con IA cómo compilar, probar y comportarse en tu proyecto. Piensa en él como un README para agentes. Codex, Cursor, GitHub Copilot y Gemini CLI lo leen, y Claude Code también lo lee ya. Como los agentes lo obedecen, un AGENTS.md plantado también es una vía de ataque.
TL;DR: puntos clave
- AGENTS.md no tiene campos obligatorios, lo usan más de 60.000 proyectos de código abierto y lo mantiene la Agentic AI Foundation, dentro de la Linux Foundation (AGENTS.md).
- Claude Code lee AGENTS.md directamente desde la versión 2.1.277, pero solo si no hay ningún CLAUDE.md en tu directorio de trabajo ni por encima (documentación de Claude Code, 2026).
- Codex apila los archivos de instrucciones desde la raíz hacia abajo y se detiene en 32 KiB por defecto (OpenAI, 2026). Copilot da prioridad al archivo más cercano (GitHub Docs, 2026).
- Un estudio revisado el 29 de septiembre de 2026 no halló mejora general en el éxito de las tareas. El coste de inferencia fue más de un 20 % mayor (Gloaguen et al., 2026).
- El 22 de octubre de 2026, Forever Security halló un AGENTS.md malicioso en la carpeta Descargas de un cliente. En sus pruebas, Codex ejecutó el malware en más del 90 % de los intentos (Forever Security, 2026).
- La documentación de Anthropic dice que Claude trata estos archivos como contexto, no como configuración obligatoria, y recomienda un hook PreToolUse para bloquear una acción (documentación de Claude Code, 2026).
De un vistazo: los datos clave en una tabla
Respuesta rápida
¿Qué debe contener un AGENTS.md y qué puede salir mal?
Incluye comandos, estilo de código, pasos de prueba y límites claros en un archivo corto en la raíz del repositorio, y añade archivos anidados para los paquetes que se diferencien. El riesgo es la confianza. Los agentes siguen el archivo que encuentran, así que revísalo como código y aplica las reglas de seguridad con permisos, no con texto.
| Pregunta | Respuesta corta |
|---|---|
| ¿Qué es? | Instrucciones en Markdown para agentes de código, sin campos obligatorios |
| ¿Dónde va? | En la raíz del repositorio, más archivos anidados para subproyectos |
| ¿Qué archivo gana si hay conflicto? | El más cercano; tu prompt en el chat anula todo lo demás |
| ¿Qué tamaño puede tener? | Codex deja de combinar archivos en 32 KiB por defecto |
| ¿Cuál es el riesgo principal? | Un archivo que no escribiste, tratado como órdenes |
| ¿Cuál es la solución? | Revisarlo como código y aplicar las reglas fuera del Markdown |
Cómo lo investigamos
El 5 de noviembre de 2026 leímos el sitio de AGENTS.md y la documentación actual de Codex, Claude Code, Cursor y GitHub Copilot. También leímos el estudio de arXiv sobre archivos de contexto, el informe de Forever Security y la nota de la Cloud Security Alliance sobre el envenenamiento de archivos de instrucciones. La tabla de herramientas y la lista de blindaje son nuestra síntesis.
Qué es AGENTS.md y qué herramientas lo leen
AGENTS.md es un formato abierto que da a los agentes de código el contexto que un README deja fuera: compilación, pruebas y convenciones. Según el sitio de AGENTS.md (2026), funciona con Codex, Cursor, Gemini CLI, GitHub Copilot, Aider, Windsurf y Devin. Un solo archivo sirve a todos los agentes de tu equipo.
El formato nació de una colaboración entre OpenAI Codex, Jules de Google, Cursor, Amp y Factory. Según la Cloud Security Alliance (2026), OpenAI lo donó a la Agentic AI Foundation de la Linux Foundation en diciembre de 2025. El sitio indica ahora más de 60.000 proyectos que lo usan.
| Herramienta | Cómo lee AGENTS.md | Ojo con |
|---|---|---|
| Codex | Archivo global en ~/.codex y después cada directorio desde la raíz del proyecto hasta tu carpeta de trabajo | Tamaño combinado limitado a 32 KiB por defecto |
| Claude Code | Solo lo lee si no hay CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo ni por encima | Requiere la v2.1.277 o posterior; si no, usa @AGENTS.md dentro de un CLAUDE.md |
| Cursor | Raíz del proyecto y subdirectorios, según la documentación de Cursor | Un .md simple en .cursor/rules se ignora, solo cuenta .mdc |
| GitHub Copilot | Cualquier AGENTS.md del repositorio, primero el más cercano, según GitHub Docs | También sirven CLAUDE.md o GEMINI.md en la raíz |
| Gemini CLI | Define context.fileName como AGENTS.md en .gemini/settings.json | Requiere configurarlo en cada proyecto |
| Aider | Añade read: AGENTS.md a .aider.conf.yml | Requiere configurarlo en cada proyecto |
En Claude Code el valor por defecto importa. Un repositorio con ambos archivos hace que Claude lea solo CLAUDE.md. Los equipos que quieren un único archivo compartido ponen @AGENTS.md al principio de su CLAUDE.md, un patrón que también explicamos en nuestra guía de Claude Code skills.
Cómo configurar tu archivo paso a paso
Crea AGENTS.md en la raíz del repositorio, mantenlo corto y escribe solo lo que un agente no puede deducir de tu código. Empieza por los comandos que debe ejecutar, sigue con convenciones y límites. Añade archivos anidados solo donde un paquete difiera de verdad, y comprueba el resultado preguntando al agente qué instrucciones cargó.
- Crea
AGENTS.mden la raíz del repositorio. La mayoría de los agentes pueden generar un primer borrador si se lo pides. - Lista los comandos exactos con sus flags, como instalar, probar y lint, cerca del principio.
- Añade reglas de estilo que difieran de las habituales y un ejemplo de código corto.
- Añade límites: qué puede hacer el agente libremente, qué requiere aprobación y qué no debe tocar nunca.
- En un monorepo, coloca otro AGENTS.md en cada paquete. Gana el archivo más cercano al código editado.
- Comprueba la carga. En Codex, ejecútalo con un prompt que pida listar las fuentes de instrucciones. En Claude Code, ejecuta
/memoryy busca la ruta.
Reglas de precedencia de un vistazo
Cada herramienta resuelve los conflictos de forma algo distinta, así que comprueba qué archivo cargó realmente tu agente antes de fiarte de él.
| Herramienta | Qué instrucciones ganan |
|---|---|
| Codex | Los archivos más cercanos a tu directorio de trabajo van después en el prompt combinado, y AGENTS.override.md sustituye a AGENTS.md en el mismo directorio |
| Claude Code | Por defecto se leen los CLAUDE.md en lugar de AGENTS.md, y AGENTS.override.md no se lee nunca |
| Cursor y Copilot | Tiene prioridad el AGENTS.md más cercano al archivo editado |
| Cualquier agente | Tu prompt explícito en el chat anula todos los archivos |
Si tu equipo ya tiene un archivo AGENT.md, el sitio de AGENTS.md sugiere renombrarlo a AGENTS.md y mantener un enlace simbólico con el nombre antiguo.
)
Ejemplos que funcionan y qué dejar fuera
Los mejores AGENTS.md son cortos, concretos y empiezan por los comandos. El análisis de GitHub de más de 2.500 archivos de agentes de 2025 halló que los más eficaces cubren seis áreas. Son comandos, pruebas, estructura, estilo de código, flujo de git y límites. También halló que un fragmento de código real vale más que párrafos de explicación.
Menos suele ser más. Según Gloaguen et al. (2026), los archivos de contexto no mejoraron en general el éxito de las tareas y elevaron el coste de inferencia en más de un 20 % de media. Los agentes siguieron bien las instrucciones, pero las descripciones generales del repositorio no ayudaron. Los autores concluyen que estos archivos sirven para prácticas fuera de lo estándar. Evita el recorrido por tu árbol de carpetas.
| Incluye | Deja fuera |
|---|---|
| Comandos exactos de compilación, prueba y lint | Una descripción larga del repositorio |
| Convenciones que tu linter no puede aplicar | Reglas que el formateador ya aplica |
| Límites: nunca tocar secretos ni código de terceros | Consejos genéricos como "escribe código limpio" |
| Enlaces a documentación más detallada | Copias de documentos que cambian a menudo |
Riesgos de seguridad de AGENTS.md y cómo blindarlo
AGENTS.md es un canal de instrucciones de confianza en el que puede escribir cualquiera que consiga colocar un archivo en tu carpeta. Los agentes lo siguen por diseño, así que un archivo envenenado puede hacer que un agente instale paquetes, reescriba su propia configuración o filtre credenciales sin ningún fallo de software. Es prompt injection entregado como archivo.
Un archivo plantado secuestró a Codex en las pruebas
El 22 de octubre de 2026, Forever Security informó de que había encontrado un AGENTS.md en la carpeta Descargas de un cliente real. Ordenaba al agente registrar un servidor e instalar function-color, un paquete npm malicioso conocido. La empresa detuvo al agente antes de que se ejecutara código. No pudo saber cómo llegó el archivo, algo que The Hacker News también recogió.
Los investigadores demostraron después que el recorrido completo funciona. Una página web puede guardar un archivo en Descargas sin ningún clic. Codex sigue un AGENTS.md en una carpeta en la que confía. Según Forever Security (2026), Codex ejecutó el malware en más del 90 % de los intentos. El CLAUDE.md propio de los investigadores redirigió el tráfico de API de Claude Code alrededor de la mitad de las veces, lo que expone el token de sesión. Los investigadores sostienen que los proveedores no tienen nada que parchear, porque el agente hizo lo que está diseñado para hacer.
El patrón es anterior a un solo incidente
Según la Cloud Security Alliance (2026), los archivos de instrucciones y de configuración se abusan desde 2025. Los casos más recientes persuaden al agente en lugar de explotar un fallo de carga.
| Caso | Fecha | Qué pasó |
|---|---|---|
| Configuración de proyecto de Claude Code (CVE-2025-59536, CVE-2026-21852) | Divulgado en febrero de 2026 | La configuración del repositorio ejecutaba hooks o enviaba una clave de API antes del aviso de confianza, corregido |
| Hooks entre herramientas de Cursor (CVE-2026-48124) | Junio de 2026 | Cursor ejecutó hooks del archivo de configuración de Claude Code, corregido en Cursor 3.0.0 |
| Gusano Miasma en Azure/durabletask | 5 de junio de 2026 | Archivos de configuración y reglas de agentes plantados ejecutaron un ladrón de credenciales, 73 repositorios deshabilitados |
| AGENTS.md en la carpeta Descargas | Octubre de 2026 | Un archivo dejado por una web dirigió a Codex, sin parche del proveedor |
Las reglas escritas no cierran la brecha. La nota de la CSA cita un preprint de agosto de 2026, sin revisión por pares, que estudió 481 archivos CLAUDE.md públicos. Concluyó que solo entre el 4 % y el 16 % de las reglas de seguridad escritas por los desarrolladores coincidían con un control integrado capaz de aplicarlas. Nuestra guía sobre MCP tool poisoning explica el mismo problema de confianza en las descripciones de herramientas.
Cómo blindar tu AGENTS.md
El objetivo es tratar los archivos de instrucciones como código y mover las reglas de seguridad a controles que el agente no pueda esquivar con palabras. Nuestra guía del OWASP Top 10 para aplicaciones agénticas muestra cómo se clasifican estos riesgos de los agentes.
| Control | Qué hacer |
|---|---|
| Revisión | Pon AGENTS.md, CLAUDE.md y la configuración de agentes bajo revisión de code owners, y busca Unicode oculto |
| Ubicación | No inicies nunca un agente en ~/Downloads ni en un repositorio que no hayas leído |
| Archivos ajenos | Lee cualquier AGENTS.md que no hayas escrito antes de que el agente abra esa carpeta |
| Aplicación | Usa permisos, sandboxes y un hook PreToolUse, no frases en Markdown |
| Vigilancia de la configuración | Revisa ~/.codex/config.toml y .claude/settings.json por si hay servidores o endpoints que no añadiste |
| Respuesta | Si se ejecutó un archivo plantado, asume que el token se filtró y rótalo |
Los controles en la máquina del desarrollador son solo una capa. Agent Gateway (TrustGate) se sitúa entre los agentes de código y los modelos y herramientas que usan. La página de asistentes de código seguros de NeuralTrust describe tres funciones. Analiza cada entrada en busca de instrucciones ocultas antes de que llegue al modelo, aprueba servidores MCP por equipo y registra cada prompt y llamada a herramientas. Un gateway ve el tráfico del modelo y de las herramientas, así que no sustituye al bloqueo de escrituras en archivos de configuración locales. Agent Runtime Security (TrustGuard) añade aplicación de políticas en línea sobre ese tráfico. Para la parte MCP, consulta nuestra guía de seguridad MCP en Claude Code y Cursor.
¿Archivo compartido o reglas por herramienta? Cómo elegir
Usa AGENTS.md como fuente de verdad compartida cuando varios agentes trabajan en un mismo repositorio. Añade un CLAUDE.md o un archivo de .cursor/rules cortos solo para el comportamiento específico de cada herramienta. Mantén un único archivo canónico, para que las instrucciones no se desvíen entre herramientas ni equipos.
| Tu situación | Mejor opción |
|---|---|
| El equipo usa Codex, Cursor y Copilot a la vez | Un AGENTS.md en la raíz y archivos anidados para paquetes |
| El equipo usa Claude Code y otros agentes | AGENTS.md más un CLAUDE.md que empiece con @AGENTS.md |
| Necesitas reglas por patrón de archivo en Cursor | .cursor/rules con archivos .mdc para reglas acotadas |
| Necesitas una regla que no se pueda romper nunca | Un permiso, hook o sandbox, no una línea de Markdown |
| Comparas agentes de código antes de estandarizar | Lee nuestra comparativa Codex vs Claude Code |
Conclusión
AGENTS.md es lo más parecido a un estándar compartido que tienen los agentes de código. Un archivo corto que empiece por los comandos rinde en Codex, Cursor, Copilot y Claude Code. Su modelo de confianza es también su punto débil, como mostró el caso de la carpeta Descargas de octubre de 2026. Trata cada AGENTS.md como código, mantén a los agentes fuera de carpetas que no controlas y aplica tus reglas de seguridad con permisos, hooks y un gateway, no con Markdown.
Protege tus agentes de código en producción con NeuralTrust
Pon un gateway entre Claude Code, Codex y Cursor y tus modelos y herramientas, para detectar instrucciones ocultas, servidores MCP sin aprobar y secretos filtrados antes de que causen daño.
)
Comparativas relacionadas
- Claude Code Skills
- Codex vs Claude Code: comparativa de benchmarks 2026
- Claude Code vs Cursor: comparativa de benchmarks 2026
- Buenas prácticas de seguridad MCP
Preguntas frecuentes sobre AGENTS.md
1. ¿Qué es AGENTS.md?
AGENTS.md es un archivo Markdown sencillo que da a los agentes de código con IA instrucciones del proyecto, como pasos de compilación, comandos de prueba y convenciones. No tiene campos obligatorios y va en la raíz del repositorio, con archivos anidados opcionales. Codex, Cursor, GitHub Copilot, Gemini CLI y Claude Code pueden leerlo.
2. ¿Dónde pongo AGENTS.md?
Ponlo en la raíz del repositorio. En un monorepo, añade otro AGENTS.md dentro de cada paquete que necesite reglas distintas. La mayoría de los agentes leen el archivo más cercano al código que editan, y Codex lee además uno global desde su directorio de inicio. Mantén cada archivo corto y concreto.
3. ¿Claude Code lee AGENTS.md?
Sí, desde la versión 2.1.277, pero solo si no hay ningún CLAUDE.md ni CLAUDE.local.md en tu directorio de trabajo ni por encima. Si tienes un CLAUDE.md, añade @AGENTS.md al principio para importarlo, o cambia el ajuste Project instructions para que lea ambos archivos.
4. ¿Qué pasa cuando las instrucciones entran en conflicto?
Gana el AGENTS.md más cercano al archivo editado, y tu propio prompt en el chat anula todo lo demás. Codex combina los archivos desde la raíz hacia abajo, de modo que los más cercanos, que van después, sustituyen a los anteriores, y revisa primero AGENTS.override.md en cada directorio. Aun así, las instrucciones contradictorias desperdician contexto, así que elimina los duplicados.
5. ¿Es seguro AGENTS.md?
El archivo es seguro cuando lo escribiste y lo revisaste tú. El riesgo es un archivo que no escribiste. Los agentes confían en el archivo de su carpeta. Forever Security mostró que un AGENTS.md plantado hacía que Codex instalara malware en más del 90 % de los intentos de prueba. Revisa estos archivos como código y no ejecutes agentes en carpetas no confiables.
6. ¿AGENTS.md mejora los resultados de los agentes?
No de forma automática. Un estudio revisado el 29 de septiembre de 2026 no halló mejora general en el éxito de las tareas. El coste de inferencia fue más de un 20 % mayor de media. Ayudan más con prácticas fuera de lo estándar, como pasos de compilación poco habituales. Mantén el archivo corto y comprueba si de verdad cambia los resultados.
7. ¿Cómo protejo AGENTS.md en mi equipo?
Pon los archivos de instrucciones y de configuración de agentes bajo revisión de code owners, busca Unicode oculto y mantén a los agentes fuera de carpetas no confiables. Aplica las reglas de seguridad con permisos, sandboxes y hooks en lugar de frases en Markdown. Dirige el tráfico de los agentes por un gateway que analice entradas y registre llamadas a herramientas, y rota los tokens si se ejecutó un archivo plantado.
Sobre el autor
Roger Howroyd es Head of Global SEO and AI en NeuralTrust, donde dirige la estrategia de búsqueda de la compañía en SEO, AEO, GEO y optimización para LLM. Está especializado en búsqueda impulsada por IA, estrategia de contenidos y SEM. Conecta con él en LinkedIn.
NeuralTrust es la plataforma líder para proteger y escalar agentes de IA. Nombrada pionera en el Gartner Emerging Market Quadrant for AI Application Security 2026, reconocida en cuatro informes Gartner Hype Cycle en 2026 y destacada en la Gartner Market Guide for Guardian Agents 2026, la Gartner Market Guide for AI Gateways 2025 y el KuppingerCole Leadership Compass for Generative AI Defense 2025. Con sede en Barcelona y oficinas en Londres y Nueva York. Certificada ISO 27001.
Fuentes
Consultadas el 5 de noviembre de 2026.
- AGENTS.md, "AGENTS.md: a simple, open format for guiding coding agents", 2026.
- OpenAI, "Custom instructions with AGENTS.md", documentación de Codex, 2026.
- Anthropic, "How Claude remembers your project", documentación de Claude Code, 2026.
- Cursor, "Rules", documentación de Cursor, 2026.
- GitHub, "Adding repository custom instructions for GitHub Copilot", GitHub Docs, 2026.
- Gloaguen et al., "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", arXiv, 12 de febrero de 2026 (v3, 29 de septiembre de 2026).
- GitHub Blog, "How to write a great agents.md: Lessons from over 2,500 repositories", 19 de noviembre de 2025.
- Forever Security, "Markdown Is the New Executable: Attackers Are Dropping Agent Instructions Into Your Downloads Folder From the Web", 22 de octubre de 2026.
- Cloud Security Alliance, "Markdown Is the New Executable: Instruction-File Poisoning of AI Coding Agents", 27 de octubre de 2026.
- The Hacker News, "Malicious File in Downloads Folder Tries to Trick AI Coding Agent Into Installing Malware", 26 de octubre de 2026.