AGENTS.md: dale instrucciones permanentes a tu agente de código

📺 Ver el video en Instagram

Cada vez que abrís un chat nuevo con tu agente, empieza desde cero. No sabe en qué proyecto está, no sabe qué stack usás, no sabe las reglas del equipo. AGENTS.md resuelve eso.

¿Qué es AGENTS.md?

AGENTS.md es un archivo de texto que vive en la raíz de tu repositorio. Cuando un agente como Claude Code o Cursor entra a trabajar en tu proyecto, lo primero que hace es leerlo.

Dentro definís todo lo que el agente necesita saber: qué stack usa el proyecto, cómo se corre, cómo se testea, las convenciones del equipo, qué cosas no tocar.

Es, básicamente, el onboarding que le darías a un desarrollador nuevo el primer día, pero para tu agente. Y lo escribís una sola vez.

AGENTS.md
└── raíz del repositorio
    └── el agente lo lee antes de empezar a trabajar

Qué va adentro: la estructura que usamos en Devlights

Un buen AGENTS.md tiene cuatro secciones bien diferenciadas. Así lo organizamos nosotros:

1. Stack

Framework, base de datos, librerías principales. El agente necesita saber con qué está trabajando antes de tocar una sola línea de código.

markdown

# Stack
- Next.js 14
- Supabase
- Tailwind CSS

2. Convenciones

Cómo nombramos variables, si usamos punto y coma o no, qué linter corre, cómo están organizadas las carpetas.

markdown

# Convenciones
- Sin punto y coma
- Comillas simples
- Componentes en PascalCase, hooks con prefijo `use`
- ESLint + Prettier configurados en el repo

3. Flujo de trabajo

Cómo se corren los tests, cómo se hace el deploy, qué branches existen y para qué sirve cada una.

markdown

# Flujo de trabajo
- Tests con Vitest antes de cada commit
- Branch `main` protegida, requiere PR
- Deploy automático a staging desde `develop`

4. Restricciones

Archivos que no debe modificar, dependencias que no debe actualizar sin avisar, patrones que el equipo decidió no usar.

markdown

# Restricciones
- No modificar /lib/core sin abrir un PR específico
- No actualizar dependencias mayores sin aprobación
- No usar `any` en TypeScript

Cuatro secciones, un archivo, y el agente arranca cada sesión sabiendo exactamente cómo trabaja tu equipo.

La diferencia en la práctica: con y sin AGENTS.md

Para entender el impacto real, vale la pena comparar el mismo pedido en dos escenarios.

Sin AGENTS.md: le pedís a Claude Code que agregue un nuevo endpoint al proyecto. El agente lo genera con la estructura que él supone correcta, con convenciones que no son las del equipo, en una carpeta que no corresponde al patrón del proyecto.

Con AGENTS.md en el repo: misma instrucción, mismo proyecto. El agente usa el stack correcto, respeta las convenciones del equipo, ubica el código en la carpeta que corresponde y corre los tests antes de terminar.

Sin AGENTS.md → agente genérico, asume y supone
Con AGENTS.md → agente de tu equipo, sigue las reglas

Nadie le dijo nada de esto en el prompt. Lo leyó solo del archivo. Esa es la diferencia entre un agente que "más o menos entiende" tu proyecto y uno que trabaja como un miembro más del equipo.

Funciona en cualquier agente, no solo en uno

Un punto importante: AGENTS.md no es un estándar de un solo proveedor. No es exclusivo de una herramienta que mañana puede cambiar de rumbo o discontinuarse.

Si mañana tu equipo cambia de agente, el archivo sigue siendo válido. No hay que reescribir nada.

Y si trabajás en equipo, el archivo va al repositorio igual que cualquier otro: todos los desarrolladores lo tienen disponible, y todos los agentes que usa el equipo, sin importar cuál elija cada persona, trabajan con el mismo contexto base.

Un archivo → múltiples agentes compatibles
En el repo → todo el equipo lo usa

Cuándo crearlo

Si arrancás un proyecto nuevo hoy, creá el AGENTS.md antes de escribir la primera línea de código. El tiempo que toma escribirlo, entre 15 y 30 minutos para un proyecto típico, se recupera muchas veces en correcciones que no vas a tener que hacer.

Si ya tenés un proyecto en marcha, nunca es tarde para agregarlo. La próxima sesión con tu agente va a empezar con todo el contexto que antes tenías que repetir manualmente.

Lo que viene en el próximo episodio

Una vez que el agente sabe cómo trabaja tu equipo, el siguiente paso es darle conocimiento experto específico: cómo instalarle skills para que no tengas que explicarle lo mismo cada vez que necesitás algo puntual.

En el próximo video vemos exactamente cómo hacerlo.