AGENTS.md: instrucciones persistentes para un proyecto
Un archivo Markdown en la raíz del repositorio que explica al agente cómo funciona tu proyecto: comandos, convenciones y cómo comprobar los cambios. Es una guía, no un mecanismo de control.
Antes de empezar
- Diseño del contexto para agentesTécnica
Qué información recibe el agente en cada momento, por qué más no siempre es mejor y cómo darle lo justo: lo esencial desde el principio y el resto cuando lo necesite.
Publicado
La idea clave:
AGENTS.mdes un README para el agente. Le cuenta, en cada tarea, lo que una persona nueva del equipo necesitaría saber el primer día. Pero es una guía: el agente puede no seguirla, así que no la uses como barrera de seguridad.
El problema
Sin instrucciones persistentes, cada tarea empieza igual: el agente explora el repositorio, adivina qué gestor de paquetes usas, prueba comandos que no existen y aplica convenciones que no son las tuyas. Puedes repetirle todo eso en cada encargo, pero es lento y acabarás olvidando algo.
AGENTS.md lo resuelve con un archivo versionado junto al código. Es un formato abierto que, según su web, usan más de 60 000 proyectos de código abierto, y lo leen agentes como Codex o Claude Code.
Cómo funciona
- El agente busca archivos
AGENTS.mdal empezar a trabajar. - Carga su contenido en el contexto, junto a tu encargo.
- Usa esas instrucciones para planificar, editar y comprobar.
Dos detalles importantes:
- Puede haber varios. Un monorepo puede tener un
AGENTS.mden la raíz y otro en cada subproyecto. Según la web oficial, el agente lee el más cercano a donde trabaja, y ese es el que manda. Cada cliente lo implementa a su manera: Codex, por ejemplo, combina los archivos desde la raíz del repositorio hasta la carpeta actual y deja de añadir cuando alcanza un límite de tamaño. - Es contexto, no configuración. La documentación de Claude Code lo dice con claridad: trata estos archivos como contexto, no como configuración que se aplica a la fuerza. Si necesitas impedir una acción, usa permisos o un sandbox (lo verás en Ejecución segura).
Qué incluir
Piensa en lo que le contarías a alguien en su primer día:
- Qué es el proyecto, en dos o tres frases.
- Comandos para instalar, ejecutar, probar y revisar el código, escritos exactamente como se usan.
- Convenciones que no se deducen del código: estructura de carpetas, estilo, nombres.
- Cómo verificar un cambio antes de darlo por terminado.
- Qué no tocar: archivos generados, migraciones ya aplicadas, configuración delicada.
Y lo que no debe ir: secretos, explicaciones largas que el agente puede leer en el propio código, ni reglas imposibles de comprobar como “escribe buen código”.
Ejemplo práctico
Un AGENTS.md breve para un proyecto pequeño:
# Guía para agentes
## Proyecto
Biblioteca de utilidades de lectura en JavaScript (ESM).
Conserva la API pública y no añadas dependencias sin justificarlo.
## Comandos
- Pruebas: `node --test`
- Formato: `npx prettier --check .`
## Convenciones
- Un módulo por archivo en `src/`; las pruebas junto al módulo (`*.test.js`).
- Nombres descriptivos en inglés.
## Antes de entregar
- Ejecuta las pruebas. Si no puedes, explica por qué.
- Revisa el diff: nada de credenciales ni archivos generados.
- Resume qué cambiaste y qué comprobaste.
Es corto a propósito: cada línea compite por la atención del agente con tu encargo. Si una regla no cambia su comportamiento, sobra.
Errores comunes
- Usarlo como sistema de seguridad. “No borres nada” ayuda, pero no impide. Las barreras reales son los permisos y el aislamiento.
- Convertirlo en una enciclopedia. Un archivo de mil líneas consume contexto y entierra lo importante. Los procedimientos largos encajan mejor en una Skill.
- Dejarlo desactualizado. Un comando que ya no existe es peor que ningún comando: el agente lo ejecutará con total confianza. Actualízalo cuando cambien los scripts.
- Mezclar obligaciones y preferencias. Distingue entre “debe” y “preferimos” para que el agente sepa qué es negociable.
Cuándo usarlo
En cuanto un proyecto tenga más de un par de tareas hechas con agentes. Es la primera capa de configuración persistente y la más rentable: unas pocas líneas ahorran exploración y errores en cada tarea. Empieza con una versión pequeña y añade una regla cada vez que veas al agente repetir el mismo error.
Siguiente paso
AGENTS.md sirve para lo que aplica a casi todas las tareas. Para procedimientos que solo hacen falta a veces —preparar una versión, añadir un endpoint—, el siguiente paso son las Skills.
Fuentes
Consultadas el 2026-10-05.
- AGENTS.md, web oficial del formato.
- Custom instructions with AGENTS.md, documentación de Codex.
- How Claude remembers your project, documentación de Claude Code.
Contenido relacionado
- Skills: procedimientos reutilizables para agentesTécnica
Una carpeta con instrucciones, y opcionalmente scripts y referencias, que enseña al agente un tipo de tarea concreto. Solo se carga cuando hace falta.
Publicado - Ejecución segura de agentesTécnica
Por qué las reglas escritas no bastan para contener a un agente y qué capas del entorno limitan el daño aunque el agente se equivoque o alguien lo engañe.
Publicado