Cómo escribir un archivo AGENTS.md para que cualquier agente de programación con IA entienda tu proyecto

Si alguna vez has visto a un agente de programación con IA ejecutar el comando de pruebas equivocado, formatear el código con un estilo que tu proyecto prohíbe o reinventar una función auxiliar que ya existe, la solución no suele ser un modelo más inteligente: es contexto. AGENTS.md es la forma estándar de darles ese contexto a los agentes, y funciona en casi todas las herramientas.

Qué es AGENTS.md en realidad

AGENTS.md es "un README para agentes": un archivo Markdown simple que colocas en la raíz de tu repositorio para indicar a las herramientas de programación con IA cómo funciona tu proyecto (agents.md). No es un lenguaje de configuración nuevo: no hay campos obligatorios ni sintaxis especial. Usa los encabezados de Markdown que quieras.

El formato importa porque es realmente compatible entre herramientas. A mediados de 2026, lo leen de forma nativa OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Devin, Aider, Zed, VS Code, JetBrains Junie y decenas más: más de 28 herramientas y más de 60.000 repositorios de código abierto (agents.md; Codersera). Ahora lo gestiona la Agentic AI Foundation de la Linux Foundation, junto con el Model Context Protocol de Anthropic. Claude Code también lee AGENTS.md, aunque su formato nativo más rico sigue siendo CLAUDE.md (DeployHQ).

Un solo archivo, y la mayoría de tus herramientas se comportan de forma coherente.

Por qué un archivo es mejor que repetirte en el chat

Cuando pegas instrucciones en un mensaje de chat, viven exactamente durante una conversación. La siguiente sesión —o el siguiente compañero de equipo, o un agente en la nube ejecutando tu tarea de noche— empieza desde cero. Un AGENTS.md se carga automáticamente al inicio de cada ejecución, así que tus convenciones se aplican por defecto en lugar de depender de si te acordaste de mencionarlas. Ese es todo el sentido: sacar el conocimiento del proyecto de tu cabeza y de chats desechables, y ponerlo en un archivo que las herramientas leen cada vez.

Qué poner en él

Piensa en lo que necesitaría un buen compañero de equipo nuevo en su primer día: eso es exactamente lo que necesita un agente. Las secciones más útiles son:

• Descripción del proyecto — un párrafo sobre qué es esto y el stack tecnológico.
• Comandos de configuración y compilación — los comandos exactos para instalar, ejecutar y compilar.
• Pruebas — cómo ejecutar las pruebas, y la regla de que las pruebas deben pasar antes de dar por terminado un cambio.
• Estilo de código — formateador, linter, convenciones de nombres, patrones a preferir o evitar.
• Directrices de commits y PR — formato de los mensajes, reglas de ramas, qué no tocar.
• Trampas — cualquier cosa no obvia que haga tropezar a la gente.

Sé concreto. "Escribe código limpio" no le dice nada a un agente. "Usa pnpm, no npm; ejecuta pnpm test antes de terminar; nunca edites archivos en src/generated/" sí es aplicable.

Un ejemplo concreto

Aquí tienes un AGENTS.md compacto para una aplicación web típica:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

Entrégaselo a Claude Code, Cursor o Copilot y cada uno adoptará las mismas reglas.

Monorepos: usa archivos anidados

En un monorepo puedes colocar un AGENTS.md en cada paquete además de uno en la raíz. Cuando un agente trabaja dentro de un subdirectorio, gana el archivo más cercano (agents.md). Mantén las convenciones compartidas en la raíz y los comandos específicos de cada paquete en los archivos anidados, de modo que un agente que edite packages/api/ obtenga automáticamente los comandos de compilación y prueba de ese paquete.

AGENTS.md vs. CLAUDE.md vs. reglas de Cursor

Quizá ya tengas archivos específicos de herramientas como CLAUDE.md o .cursor/rules. No tienes que descartarlos. En la práctica, los equipos ponen las convenciones compartidas e independientes de la herramienta en AGENTS.md —lo que todo agente necesita— y mantienen los extras específicos de cada herramienta en el archivo nativo de la herramienta que admite funciones más ricas (DeployHQ). Claude Code, por ejemplo, lee ambos, con CLAUDE.md como su formato más expresivo. Un patrón habitual es mantener un único AGENTS.md canónico y, donde una herramienta necesite su propio archivo, apuntar ese archivo hacia AGENTS.md para que haya una única fuente de verdad. Empieza con AGENTS.md; recurre al archivo específico de la herramienta solo cuando necesites una función que solo ella admita.

Mantenlo corto y específico

Más no es mejor. Un AGENTS.md gigantesco que repite toda tu guía de estilo compite por la atención del modelo y sepulta las reglas que de verdad importan. Apunta al puñado de cosas que un agente hará mal sin orientación: el comando no obvio, el directorio que no hay que tocar, el patrón que prefiere tu base de código. Si una regla ya es obvia a partir del código, probablemente no necesitas escribirla.

Cómo mantenerlo útil

Un AGENTS.md justifica su valor solo si sigue siendo cierto. Trátalo como código: cuando cambie un comando o una convención, actualiza el archivo en el mismo commit. Y cuando un agente cometa el mismo error dos veces, no te limites a corregirlo en el chat: escribe la regla. Ese único hábito convierte cada tropiezo en una solución permanente, y es lo más rentable que puedes hacer para que los agentes de IA sean fiables en tu proyecto.