Aprendiendo a configurar mis agentes de programación I: AGENTS.md
No se si a ti también te pasa, pero a mi me cuesta mucho mantenerme al día de todas las novedades que surgen alrededor de la inteligencia artificial y el nuevo término de moda, "agente". Hasta hace no mucho, estaba definiendo workflows y rules en Windsurf y todo iba bien, pero luego llegué a Claude Code y ahora tenía que utilizar un archivo llamado CLAUDE.md en el que podía configurarle todo lo que quisiera pero con una estructura distinta a las rules. Para mi todo esto es muy confuso (y bastante molesto la verdad). Parece que otras personas en mi misma situación, muy inteligéntemente, han decidido mover ficha e intentar unificar cómo se configuran todos estos agentes, para que no tengamos que dejar completamente de lado a nuestras familias y nuestro círculo social solo para seguir cobrando cada mes.
En este artículo voy a recoger mis apuntes sobre la mejor manera de generar el AGENTS.md.
Todo lo que se comentará en este artículo es similar para el archivo CLAUDE.md
Empecemos por el principio ¿Qué es y para qué sirve un AGENTS.md?
El AGENTS.md es un documento Markdown diseñado para proporcionar contexto a los agentes de Inteligencia Artificial. Principalmente utilizado para los agentes de escritura de código, pero realmente sirve para cualquier tipo de agente que utilice modelos generativos.
El formato Markdown se debe principalmente a que los modelos han sido entrenados con enormes cantidades de repositorios de código y sus archivos README. Los archivos README utilizan formato Markdown, por lo que es casi natural para los agentes y es más fácil de leer y mantener por humanos con respecto a otros formatos como XML o JSON.
El objetivo principal de este archivo es dar contexto a nuestra IA favorita para que comprenda mejor la organización, la arquitectura y la metodología de trabajo que queremos utilizar en el proyecto. Mediante esta configuración conseguiremos un mejor alineamiento del agente con nuestra forma de trabajar y reduciremos las alucinaciones (No cuentes con que las alucinaciones desaparezcan, pero tenemos mecanismos para minimizarlas)
El documento puede proporcionar la siguiente información al agente:
- Contexto del proyecto: Da información básica sobre el objetivo del proyecto y el alcance del mismo.
- Pautas para el comportamiento del agente: Permite indicar al agente qué comportamiento debe seguir en el momento de tomar decisiones
- Convenciones : Podemos indicar al agente las convenciones que debe seguir para trabajar
- Restricciones: Podemos indicar al agente líneas que no debe cruzar y acciones que no debe llevar a cabo sin autorización.
- Flujos de trabajo: Podemos indicar al agente cómo proceder en cada parte del ciclo de vida del desarrollo de una funcionalidad e incluso indicarle cómo utilizar otros agentes.
Investigaciones recientes sugieren que los archivos AGENTS.md más eficaces suelen contener únicamente las instrucciones y restricciones realmente necesarias, evitando información redundante o requisitos innecesarios.
https://arxiv.org/abs/2602.11988
¿Qué tengo que hacer para crear un AGENTS.md?
Para crear un AGENTS.md (o CLAUDE.md) debes seguir los siguientes pasos
- Crea un archivo AGENTS.md en la raíz del proyecto
- Añade las secciones más relevantes para que el agente trabaje de forma efectiva. Algunas secciones utilizadas frecuentemente pueden ser
- Resumen del proyecto
- Comandos de compilación , pruebas etc..
- Guía de estilos de código
- Instrucciones de testing
- Políticas de seguridad.
- flujos de trabajo.
- Instrucciones adicionales: Por ejemplo la estructura de los mensajes de commit
El listado anterior es una guía para darte ideas sobre las secciones que puedes poner en tu primer AGENTS.md, pero tu archivo de configuración puede tener las secciones que tu quieras. Más adelante, veremos algunas pautas para optimizar el rendimiento de tu configuración.
Mi primer AGENTS.md. ¡Por fin!
Sé que esto es a lo que has venido, para ver cómo se crea un archivo AGENTS.md porque quieres ganar velocidad programando y sin embargo estás leyendo un blog random en internet. Pero si estás aquí también significa que no eres "Vibe Coder" ni "10x Engineer". Vamos, quieres hacer las cosas bien y entender lo que pasa así que, un poco de paciencia.
A continuación te presento un AGENTS.md para un proyecto ficticio en Django, que contiene las secciones básicas indicadas anteriormente. No es necesario que tu primera AGENTS.md sea tan extenso como el que te presento a continuación o que contenga todas estas secciones y restricciones. Más adelante te explicaré cuál es la mejor manera de conseguir un AGENTS.md más eficiente.
Directrices para crear un AGENTS eficiente
El enfoque correcto en el momento de crear un AGENTS.md es usarlo para definir comportamientos y preferencias en el proyecto, no lo utilices para proporcionar datos técnicos que el propio agente ya puede obtener por sí mismo. La clave para una buena definición del agente radica en la orientación conductual. evita sobrecargar al agente con información redundante que pueda confundirlo.
A continuación te doy una serie de pautas a seguir, hay muchas más pero éstas te servirán como guía para empezar.
1 - Se específico no genérico
Directrices como "Escribe código limpio" no aporta información real al agente, en su lugar es mejor dar una serie de pautas:
- "Escribe nombres descriptivos, por ejemplo en lugar de
for item in items_listescribe código tipofor product in order_products". - "Las funciones no deben tener más de 50 líneas"
- "Prueba todas las funcionalidades con la skill 'agent-browser'
Además siempre que puedas proporciona ejemplos de lo que necesitas, esto mejorará mucho la comprensión del agente.
2 - Indica los comandos exactos para realizar las acciones
Indica al agente los comandos exactos que debe utilizar para realizar determinadas acciones. Por ejemplo:
En lugar de:Ejecuta los test en docker
Es mejor:Ejecuta los test utilizando 'docker compose run web pytest'
3 - Indica las restricciones de forma específica y clara.
Es importante indicar al agente aquellas acciones que no quieres que realice bajo ninguna circunstancia, en una sección como la del siguiente ejemplo
## Lo que NUNCA debes hacer
- NO modifiques archivos fuera del directorio del proyecto
- NUNCA instales dependencias sin que yo te las confirme primero.4 - Utiliza archivos AGENT para secciones o subdirectorios concretos.
Nuestro proyecto puede contener archivos AGENTS.md que sean específicos para secciones o subdirectorios concretos. El archivo principal será siempre el que definamos en la raíz del proyecto y será el que se cargue siempre al inicio de la sesión de trabajo. Los archivos AGENTS declarados en subdirectorios, se cargarán solamente cuando el agente trabaje sobre ese subdirectorio.
5 - No proporciones la documentación directamente en el archivo AGENTS
He visto muchos tutoriales donde te indican que debes proporcionar la documentación sobre tu proyecto, tu arquitectura etc... dentro del archivo AGENTS.md. Como veremos más adelante, proporcionar demasiada información puede confundir al agente. Es mejor que tengas un directorio docs/ dentro de tu proyecto donde guardes la documentación concreta (por ejemplo la documentación de la arquitectura) y que proporciones al agente el contexto necesario para utilizar esa documentación cuando la necesite por ejemplo, podemos dar la siguiente pauta cuando la tarea sea de backend.
Si la tarea afecta al backend, revisa docs/backend_architecture.md y valida que el diseño respeta sus capas y dependencias.
6 - Mantén el archivo con una longitud razonable
A pesar de la creencia general, Lo importante no es la cantidad de información que proporcionas al agente sino la calidad de la misma. Un archivo de configuración demasiado grande puede confundir al agente y hacer que acabe comportándose de forma inesperada. Intenta mantener el archivo principal con una longitud razonable (Un máximo de 2000 palabras suele ser la recomendación general) Si necesitas proporcionar más contexto al agente, puedes crear archivos AGENTS.md para módulos o secciones concretas de tu código que se cargarán solamente cuando el agente necesite trabajar sobre ese módulo o sección.
Prioridad de las Instrucciones del AGENT.md
Las instrucciones que proporcionamos al agente en nuestro AGENT pueden entrar en conflicto con otras instrucciones que ha recibido el agente, ya sea en el contexto en el que estamos trabajando, en la conversación o con directrices previas que hayamos proporcionado. Cuando varias directrices entran en conflicto, el agente utiliza la siguiente jerarquía de prioridad para seleccionar que pauta debe seguir..
- System Prompt: Reglas definidas por la herramienta o proveedor del agente.
- Instrucciones del usuario: Lo que pides en la conversación.
- AGENTS.md / CLAUDE.md: Reglas y preferencias que definimos para el proyecto.
- Memoria o contexto previo: Preferencias que el modelo recuerda de las sesiones anteriores.
Por ejemplo, si en tu AGENTS.md pones:
Nunca preguntes antes de escribir código
Pero el durante la conversación le dices:
Antes de programar, explícame tu plan
El agente normalmente obedecerá la instrucción que le has dado en la conversación porque su instrucción tiene más prioridad.
Es importante entender esto porque un AGENTS.md no controla completamente al agente; simplemente influye en su comportamiento dentro de los límites establecidos por instrucciones de mayor prioridad.
Consideraciones finales
No intentes construir el AGENTS.md definitivo desde el primer minuto. En su lugar comienza por lo mínimo necesario y ve añadiendo reglas, restricciones y contexto a medida que las vayas necesitando. Además, ten en cuenta que aunque los archivos AGENTS.md se están convirtiendo en el estándar de facto, cada agente puede interpretarlo de forma ligeramente distinta y la efectividad de cómo defines cada restricción puede variar entre diferentes modelos. Mi recomendación es que, a parte de comenzar poco a poco, valides cada modificación que vayas realizando. Prueba y refina cada nueva regla y de esta forma obtendrás el mejor resultado posible, estoy seguro.
En próximos artículos veremos cómo utilizar otros elementos como Skills, rules y subagentes para aprovechar todo el potencial que los agentes pueden proporcionarnos.
Fuentes consultadas.
Si, aunque no te lo creas este artículo ha sido escrito de forma artesanal, leyendo otros artículos y fuentes y todo a mano, palabra por palabra (Aunque por supuesto me he ayudado de Inteligencia Artificial en la investigación).
Estas son las fuentes que he consultado, te recomiendo que las revises porque merecen mucho la pena.
David Abad
manuel.aguilar
Guillem Estapé
Thibaud Gloaguen