---
title: "AGENTS.md: dale instrucciones permanentes a tu agente de código"
description: "Qué es AGENTS.md, qué información poner adentro y cómo cambia el comportamiento de Claude Code, Cursor o Windsurf en tu proyecto. Con ejemplos reales. Devlights Tech Tips, episodio 3."
url: "https://www.devlights.com/es/blog/agents-md-instrucciones-agente-codigo"
language: es
published: 2026-10-20T13:00:00.000Z
updated: 2026-10-28T22:29:54.297Z
type: article
authors: ["Franco Piccoli"]
category: "Tech Tips"
tags: ["AGENTS.md", "Agentes de código", "Claude Code", "Cursor", "Windsurf", "IA", "Desarrollo de software", "Tech Tips", "Productividad dev"]
---

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

> Qué es AGENTS.md, qué información poner adentro y cómo cambia el comportamiento de Claude Code, Cursor o Windsurf en tu proyecto, con ejemplos reales.

> **TL;DR**
>
> **Este artículo es parte de la serie Devlights Tech Tips sobre IA aplicada al trabajo técnico.** Si te perdiste los episodios anteriores, podés arrancar por modelo, agente y herramienta o seguir con tokens y context window.

📺 [**Ver el video en Instagram**](https://www.instagram.com/reel/DZf6zO7J78B/)

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.

| Herramienta | Soporte |
| --- | --- |
| Claude Code | ✅ Nativo |
| Cursor | ✅ Nativo |
| Windsurf | ✅ Nativo |
| Gemini CLI | ✅ Nativo |

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.