🧠 Agents.md: La Memoria Persistente para tus Agentes de IA
A medida que trabajas con agentes de programación impulsados por inteligencia artificial, aparece un problema muy habitual:
Tener que repetir constantemente las mismas instrucciones.
Por ejemplo:
- No utilizar dependencias externas.
- No usar determinados frameworks.
- Utilizar una herramienta concreta en lugar de otra.
- Seguir ciertas decisiones de arquitectura.
Repetir estas indicaciones en cada conversación es ineficiente, consume tokens y aumenta la probabilidad de que el agente termine ignorando alguna restricción importante.
Para solucionar este problema existe agents.md.
📄 Qué es un archivo agents.md
El archivo agents.md es un documento especial que permite describir cómo debe comportarse la inteligencia artificial dentro de un proyecto.
OpenCode puede generarlo automáticamente mediante el comando:
/initAl ejecutarlo, se crea un archivo agents.md en la raíz del repositorio.
Este archivo funciona como una especie de documentación operativa para los agentes de IA.
🎯 Para qué sirve
La idea principal es almacenar información que quieres que el agente recuerde siempre.
Por ejemplo:
- Decisiones de arquitectura.
- Restricciones técnicas.
- Herramientas permitidas.
- Dependencias autorizadas.
- Convenciones del proyecto.
- Comandos habituales.
En lugar de repetir estas instrucciones continuamente, el agente puede consultarlas automáticamente cada vez que trabaja sobre el repositorio.
🏗️ Definir decisiones de arquitectura
Uno de los usos más importantes consiste en documentar decisiones técnicas.
Por ejemplo:
- El proyecto debe ser Vanilla JavaScript.
- No se permiten frameworks.
- No se permiten dependencias externas.
- No debe existir proceso de build.
- Se debe utilizar una herramienta específica para ejecutar el proyecto.
De esta forma, cuando el agente genere nuevo código, tendrá en cuenta esas restricciones desde el principio.
🚫 Evitar dependencias no deseadas
Un problema habitual al trabajar con IA es que muchas veces intenta resolver problemas añadiendo librerías nuevas.
Sin embargo, hay proyectos donde esto no es deseable.
Un archivo agents.md puede incluir reglas como:
No npm dependencies
No frameworks
No build stepAsí el agente entiende el contexto del proyecto y evita introducir cambios que rompan las decisiones previamente tomadas.
🔧 Personalizar el comportamiento del agente
El contenido de agents.md no es fijo.
Puedes modificarlo manualmente o pedirle al propio agente que lo actualice.
Por ejemplo:
Always use Bun instead of NodeA partir de ese momento, cuando el agente necesite ejecutar comandos o levantar servidores, tendrá en cuenta esa preferencia automáticamente.
🤖 El agente consulta agents.md de forma automática
Una de las ventajas más interesantes es que no necesitas recordar constantemente las restricciones.
Cuando realizas una petición como:
Levanta el servidor de desarrollo.
El agente puede leer previamente el contenido de agents.md y aplicar las reglas definidas allí.
Esto permite mantener un comportamiento consistente incluso entre sesiones diferentes.
🌍 Un estándar abierto
Aunque OpenCode utiliza esta funcionalidad, agents.md no es una invención exclusiva de OpenCode.
Se trata de una especificación abierta adoptada por múltiples herramientas del ecosistema.
Actualmente puede encontrarse en herramientas como:
- Claude Code
- OpenCode
- Cursor
- Visual Studio Code
- Otros agentes de programación basados en IA
Esto facilita compartir configuraciones entre distintas plataformas.
✍️ Cuanto más simple, mejor
Un error común consiste en convertir agents.md en un documento enorme.
Sin embargo, la recomendación es mantenerlo:
- Corto.
- Directo.
- Específico.
- Fácil de entender.
Hay que recordar que el agente necesita procesar este contenido continuamente.
Cuanto más conciso sea, mejor funcionará y menos tokens consumirá.
📦 Debe formar parte del repositorio
El archivo agents.md no debería quedarse únicamente en tu ordenador.
Es recomendable incluirlo dentro del repositorio para que cualquier miembro del equipo disponga exactamente de las mismas reglas.
De esta forma:
- Todos los desarrolladores comparten el mismo contexto.
- Los agentes trabajan bajo las mismas restricciones.
- Se reduce la aparición de comportamientos inconsistentes.
⚠️ La última palabra siempre la tiene el usuario
Existe un detalle muy importante:
El contenido de agents.md no tiene prioridad absoluta.
Si el usuario da una instrucción explícita que contradice el archivo, el agente normalmente obedecerá la petición del usuario.
Por ejemplo, aunque el archivo indique:
Siempre utiliza BunSi el usuario ordena expresamente:
Usa Node para levantar el servidorEl agente seguirá la instrucción más reciente.
Por tanto, agents.md debe entenderse como una guía persistente, no como una restricción inquebrantable.
📌 Ideas clave de esta clase
Quédate con estos conceptos:
agents.mdpermite almacenar reglas permanentes para los agentes de IA.- Puede generarse automáticamente mediante
/init. - Sirve para documentar decisiones técnicas y arquitectónicas.
- Evita repetir instrucciones constantemente.
- Ayuda a mantener coherencia entre sesiones.
- Es una especificación abierta utilizada por múltiples herramientas.
- Debe mantenerse corto y específico.
- Conviene incluirlo dentro del repositorio.
- El usuario siempre conserva la última palabra sobre las decisiones del agente.
🚀 Construyendo agentes más consistentes
A medida que los agentes de programación se convierten en parte habitual del flujo de trabajo, herramientas como agents.md resultan fundamentales.
No solo reducen el coste en tokens y la repetición de instrucciones, sino que también ayudan a mantener una forma de trabajo consistente entre personas, sesiones y herramientas distintas.
Una pequeña inversión en definir correctamente este archivo puede evitar muchos errores y malentendidos en el futuro.
💡 Tip: Empieza con un
agents.mdmuy pequeño. Añade únicamente las restricciones y decisiones realmente importantes. Si intentas documentarlo todo desde el principio, terminarás creando un archivo difícil de mantener y menos efectivo para la IA.