AGENTS.md, parte 1: qué es y cómo empezar

Un AGENTS.md es un archivo Markdown de instrucciones para agentes de inteligencia artificial que trabajan dentro de un repositorio. Podemos pensarlo como una guía de bienvenida: le dice al agente qué hay en el proyecto, cómo debe moverse, qué debe cuidar y qué cosas no debería hacer sin pedir permiso.

Aunque el concepto nació muy cerca del mundo de la programación, no sirve solo para código. También puede ayudar en repositorios de apuntes, documentación, investigación, guiones, borradores, materiales de clase o archivos de trabajo. Si guardas información en carpetas y quieres que una IA te ayude a ordenarla, resumirla, revisarla o transformarla sin desacomodar todo, este archivo puede ser un buen punto de partida.

Herramientas como Codex, Claude Code, Cursor, GitHub Copilot, Gemini CLI y otros asistentes pueden buscar instrucciones dentro del repositorio para entender mejor cómo colaborar. No todos los agentes leen exactamente lo mismo ni se comportan igual, pero la idea general es cada vez más común: antes de actuar, el agente necesita contexto.

Esta es la primera parte de una serie. Aquí vamos a ver los conceptos generales y una plantilla inicial para empezar. En la segunda parte veremos cómo aplicarlo a proyectos técnicos. En la tercera parte veremos usos cotidianos que no dependen de programar.

Por qué un agente necesita instrucciones

Cuando un agente entra a un repositorio, no siempre sabe qué debe hacer primero. Puede ver archivos, carpetas y texto, pero eso no significa que entienda las reglas del proyecto. No sabe automáticamente qué carpetas son importantes, qué archivos no debería tocar, qué tono debe respetar, qué datos son sensibles o qué resultado esperas al final.

Sin instrucciones, un agente puede hacer algo útil, pero también puede mezclar temas que debían estar separados, borrar contenido ya revisado, tocar archivos que no correspondían o resolver una tarea de una forma que no encaja con tu manera de trabajar. Muchas veces el problema no es que la IA sea mala, sino que entró al proyecto sin contexto.

Un AGENTS.md reduce ese riesgo. No controla todo, pero orienta. Le dice al agente: este es el objetivo del proyecto, estas son las carpetas principales, estas son las reglas de trabajo, estos son los límites y así debes cerrar una tarea.

Dónde se coloca

El archivo se crea normalmente en la raíz del proyecto o repositorio, con este nombre:

AGENTS.md

La extensión .md significa Markdown. Esto permite usar encabezados, listas y bloques de código de forma clara, algo que ayuda tanto a personas como a herramientas automáticas. La raíz es el primer nivel de tu carpeta: el lugar donde suelen estar el README.md, las carpetas principales, la documentación, los apuntes o los archivos de configuración.

En proyectos grandes también pueden existir archivos AGENTS.md dentro de subcarpetas, con reglas específicas para cada parte. Pero si estás empezando, conviene crear uno general y mantenerlo simple.

Qué debería incluir una primera versión

Un buen primer AGENTS.md no necesita cubrir todo. Lo importante es que ayude al agente a no trabajar a ciegas. Para empezar, alcanza con cuatro bloques: contexto, estructura, reglas y cierre de tarea.

El contexto explica qué es el proyecto. La estructura muestra dónde está cada cosa. Las reglas dicen cómo trabajar y qué evitar. El cierre de tarea indica qué debe informar el agente antes de terminar.

Una primera versión podría ser esta:

# Instrucciones para agentes

## Contexto del proyecto

Este repositorio contiene materiales de trabajo sobre tecnología e inteligencia artificial. El objetivo es mantener la información clara, ordenada y fácil de reutilizar.

## Estructura

- `apuntes/`: notas de trabajo.
- `borradores/`: ideas no publicadas.
- `recursos/`: enlaces y referencias.
- `publicado/`: material ya revisado.

## Reglas de trabajo

- Mantener cambios acotados.
- Separar temas distintos en archivos distintos.
- No inventar fuentes, fechas ni datos.
- No borrar contenido publicado sin pedir confirmación.
- Marcar como pendiente cualquier información que necesite validación.

## Antes de terminar

- Indicar qué archivos cambiaste.
- Explicar brevemente qué hiciste.
- Avisar si algo necesita revisión humana.

Esta plantilla ya alcanza para empezar. No es perfecta, pero le da al agente un mapa básico.

Cómo escribir buenas reglas

Las reglas tienen que ser concretas. Una regla vaga obliga al agente a adivinar. Por ejemplo, “hazlo bien” no ayuda demasiado. En cambio, “mantén el tono claro y separa temas distintos en archivos distintos” da una instrucción aplicable.

También conviene decir qué no quieres que haga. A veces los límites negativos son tan importantes como las instrucciones positivas. Por ejemplo:

## Instrucciones que debe evitar

- No mezclar apuntes personales con textos listos para publicar.
- No convertir un resumen en noticia sin validar fuentes.
- No mover archivos si el destino no está claro.
- No borrar archivos porque parezcan viejos.

Estas reglas no frenan al agente; le dan bordes. Y esos bordes hacen que el resultado sea más fácil de revisar.

Qué no debes poner

No pongas contraseñas, tokens de API, usuarios, claves privadas, datos personales o información sensible. AGENTS.md debe tratarse como documentación operativa, no como un lugar para guardar secretos.

Tampoco conviene llenarlo de reglas contradictorias. Si una parte dice “cambia todo lo que haga falta” y otra dice “no modifiques la estructura”, el agente puede elegir mal. Es mejor escribir menos reglas, pero más claras.

Cómo probar si funciona

Después de crear tu primera versión, pídele al agente una tarea pequeña. No empieces con algo crítico. Prueba con algo que puedas revisar fácilmente.

Por ejemplo:

Lee AGENTS.md y ordena estos apuntes en dos archivos separados. Antes de terminar, dime qué regla aplicaste y qué archivos cambiaste.

Luego revisa si respetó la estructura, si evitó tocar archivos sensibles y si su respuesta final te ayudó a entender qué hizo. Si algo falló por falta de contexto, agrega una regla breve. Si una regla no aporta nada, bórrala.

Siguiente paso

La mejor forma de usar AGENTS.md es empezar simple y mejorarlo con el uso. No intentes escribir el documento perfecto el primer día. Crea una base, úsala en tareas pequeñas y ajusta cuando veas errores reales.