Qué es Agents.md y cómo usarlo en tu proyecto
Autor: Redacción Domeny.ForSale Publicado
En pocas palabras: AGENTS.md es un archivo de texto con instrucciones para agentes AI que trabajan en un proyecto, normalmente en su código. Describe, entre otras cosas, cómo ejecutar las pruebas, cómo se organiza el proyecto y qué reglas seguir al introducir cambios. No ejecuta nada por sí mismo: su efecto depende de si la herramienta utilizada lee el archivo y de cómo interpreta sus indicaciones.
Para qué sirve el archivo AGENTS.md
Un agente AI es una herramienta que no solo responde preguntas, sino que también puede realizar tareas, como explorar archivos, editar código y ejecutar comandos. Para ello necesita conocer el contexto del proyecto concreto. Sin ese contexto, puede elegir un método incorrecto para instalar las dependencias o modificar archivos que el equipo no edita manualmente.
AGENTS.md permite guardar ese contexto en el repositorio, es decir, el lugar donde se almacenan el código y su historial de cambios. El archivo utiliza Markdown, un formato de texto sencillo que admite encabezados, listas y bloques de código. Se puede modificar con un editor de texto convencional y revisar junto con los demás cambios del proyecto.
Es una convención para transmitir instrucciones, no un programa, un modelo AI ni un mecanismo para conceder permisos. La indicación «no cambies la configuración de producción» orienta al agente, pero no impide técnicamente el acceso a esa configuración.
AGENTS.md y README: distintas funciones de la documentación
README.md suele presentar el proyecto a las personas: explica para qué sirve, cómo instalarlo y cómo empezar a usarlo. AGENTS.md se centra en cómo debe trabajar el agente en ese repositorio. Ambos archivos pueden complementarse, en lugar de duplicar la misma documentación.
Por ejemplo, el README de una biblioteca puede mostrar cómo utilizarla en una aplicación propia. Las instrucciones para el agente, en cambio, pueden establecer que, tras modificar la interfaz pública, hay que actualizar los ejemplos y ejecutar un conjunto concreto de pruebas.
Tampoco hay que confundir AGENTS.md con llms.txt, un archivo propuesto como forma de proporcionar a los modelos de lenguaje información sobre el contenido de un sitio web. AGENTS.md trata principalmente del trabajo en el proyecto, no de presentar el contenido de la web. Su presencia no indica que el sitio sea visible en buscadores ni en servicios de AI.
Dónde colocar el archivo y si todas las herramientas lo leen
Lo habitual es colocarlo en el directorio raíz del repositorio. Al crear el archivo, utiliza el nombre AGENTS.md, en mayúsculas: en los sistemas que distinguen entre mayúsculas y minúsculas, Agents.md puede ser un archivo distinto. No des por hecho que la herramienta reconocerá cualquier variante del nombre.
En proyectos más grandes puede haber archivos AGENTS.md adicionales en subdirectorios, por ejemplo, uno para la interfaz de usuario y otro para la parte del servidor. Esto permite separar las reglas de las distintas tecnologías. Sin embargo, el ámbito de aplicación de las instrucciones y la forma de resolver las contradicciones dependen de la herramienta, por lo que no hay que asumir una jerarquía común a todos los agentes.
Antes de incorporarlo al proyecto, consulta en la documentación oficial del agente que utilizas:
- si admite
AGENTS.mdy si requiere configuración adicional; - en qué directorios busca las instrucciones;
- si lee los archivos de los subdirectorios;
- cómo combina esas instrucciones con la petición del usuario y otras instrucciones.
Añadir el archivo al repositorio no significa que todas las funciones de AI del editor vayan a utilizarlo.
Qué incluir en las instrucciones para el agente
La información más útil es la que evita que el agente tenga que hacer suposiciones: comandos que realmente funcionan, la ubicación de los archivos importantes y los límites del cambio solicitado. Una recomendación genérica como «escribe buen código» no le indica cómo verificar el resultado.
Un archivo de ejemplo para un proyecto de JavaScript que utiliza npm podría ser el siguiente. Los comandos solo tienen sentido si se corresponden con la configuración del repositorio:
## Trabajo en el proyecto
## Ejecución y verificación
- Instala las dependencias con el comando `npm ci`.
- Ejecuta las pruebas con el comando `npm test`.
- Comprueba el cumplimiento de las reglas del código con el comando `npm run lint`.
- Si no puedes realizar alguna comprobación, indica el motivo.
## Organización de los archivos
- El código de la aplicación se encuentra en `src/`.
- No edites manualmente el directorio `generated/`.
## Alcance de los cambios
- No añadas dependencias sin la confirmación del usuario.
- Al corregir un error, añade una prueba que lo reproduzca.
- No combines la corrección con tareas de limpieza del código que no estén relacionadas.
En un proyecto con varias aplicaciones, indica también el directorio desde el que debe ejecutarse cada comando. Si las pruebas requieren un servicio adicional, describe ese requisito y cómo preparar el entorno de forma segura. No incluyas contraseñas, tokens ni otros secretos en las instrucciones.
Cómo comprobar su eficacia y mantenerlo actualizado
Una buena forma de comprobarlo es encargar una tarea pequeña, como corregir la validación de un único campo de un formulario. Observa si el agente utiliza los comandos adecuados, evita los archivos generados automáticamente e informa de las pruebas que no ha ejecutado. Si la herramienta muestra qué instrucciones ha cargado, comprueba también esa información.
Cuando el agente cometa un error, averigua primero si ha leído el archivo. Añadir más prohibiciones no ayudará si el problema es que la herramienta no lo admite o que está en una ubicación incorrecta. Si el agente ha leído la instrucción, sustituye cualquier indicación ambigua por una acción o condición concreta.
Trata AGENTS.md como parte de la documentación que debes mantener: actualízalo cuando cambien los comandos, la estructura de directorios o el proceso de pruebas. Haz cumplir las restricciones de acceso mediante los permisos y la configuración del entorno, no solo mediante frases en el archivo. Para empezar, anota los comandos de verificación que funcionan y las restricciones más importantes; después, comprueba su aplicación con una tarea pequeña.
Consulta también: ¿Qué es GitHub?
Lee también
