AGENTS.md junto a CLAUDE.md, un contexto de repo para varias herramientas de IA

Tienes un CLAUDE.md limpio. Tu montaje funciona. Entonces se incorpora un compañero que trabaja con Codex. Una semana después alguien prueba Cursor. De repente estás explicando los mismos comandos de instalación tres veces, una por herramienta, en ficheros de configuración distintos. AGENTS.md resuelve eso. Un fichero que leen Claude Code, Codex, Cursor, Gemini CLI, Aider, Continue y VS Code Copilot. Según agents.md lo usan más de 60.000 proyectos de código abierto. Este playbook enseña cómo montar AGENTS.md además de tu CLAUDE.md sin tener que mantener el contenido por duplicado.

Paso 1: Entender qué es AGENTS.md en realidad

AGENTS.md es una convención abierta, no una funcionalidad de Anthropic ni de Cursor. El fichero está en la raíz del repo y contiene lo que una herramienta de IA para código necesita saber para trabajar con sentido en el proyecto. Comandos de instalación, comandos de test, estilo de código, reglas de PR. La idea viene del entorno de OpenAI Codex y se extendió en 2025 y 2026, porque si no cada fabricante se habría inventado su propio nombre de fichero de configuración.

Conviene saberlo: AGENTS.md no es magia. Es solo un fichero que las herramientas leen porque reconocen el nombre. Claude Code no lo lee automáticamente (lee CLAUDE.md), pero si metes una referencia en tu CLAUDE.md, Claude llega igualmente. Más sobre esto en el paso 7.

Paso 2: Cuándo compensa tener además AGENTS.md

Si trabajas tú solo con Claude Code y nunca tocas otra herramienta, puedes dejar AGENTS.md fuera. Con CLAUDE.md basta.

Pero en cuanto se cumpla al menos uno de estos puntos, el segundo fichero merece la pena:

• Varias personas del equipo usan herramientas de IA distintas (Codex, Cursor, Copilot)
• Tienes código abierto y quieres que quien contribuya desde fuera pueda arrancar directo con su propio montaje
• Tú mismo cambias a veces de herramienta (por ejemplo Claude Code a diario, Codex en la CI)
• Tu repo lo usan bots de codificación automática como Sourcegraph Cody o Copilot Coding Agent

En el repo de StudioMeyer usamos los dos. CLAUDE.md para los hooks, skills y notas de memoria específicos de Claude. AGENTS.md para todo lo que es agnóstico de herramienta: comandos de build, montaje de tests, reglas de PR.

Paso 3: Decidir la estructura, un fichero o varios

AGENTS.md puede estar en varios sitios del repo. En la raíz vale globalmente. En un subdirectorio sobrescribe al de la raíz para los ficheros de ese directorio. Para monorepos eso es importante.

Para un repo normal de un solo paquete: basta un AGENTS.md en la raíz.

Para un monorepo con varios paquetes: un AGENTS.md en la raíz con los comandos globales, más un AGENTS.md por workspace con las indicaciones propias de ese paquete. Más sobre esto en el paso 9.

Paso 4: Crear el primer AGENTS.md

En la raíz del repo:

touch AGENTS.md
git add AGENTS.md

Una estructura que funciona bien:

# Project Name

Una frase corta sobre qué es el repo.

## Setup commands

- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons
- Patrones funcionales donde se pueda

## Testing instructions

- Vitest con `pnpm test`
- Centrarse en un fichero de test: `pnpm vitest run -t "test name"`
- La CI corre en .github/workflows/test.yml

## PR instructions

- Formato de título: `[scope] short description`
- Antes de cada commit: `pnpm lint && pnpm test`
- Solo squash merges

Ese es el esqueleto. Normalmente más corto que CLAUDE.md, porque solo contiene las cosas agnósticas de herramienta.

Paso 5: Meter bien los comandos de instalación y de test

Aquí está el quid. Cuando una herramienta de IA nueva toca tu repo, el primer comando que lanza es casi siempre instalar más testear. Si eso no está claro en AGENTS.md, la herramienta adivina. A veces bien, a menudo mal.

Un ejemplo concreto de nuestro repo de la Academy. Antes de AGENTS.md, las herramientas nuevas probaban casi siempre npm install (nosotros usamos pnpm). Tres minutos perdidos, y luego un conflicto de lockfile. Con AGENTS.md, en la segunda línea pone pnpm install, y la herramienta arranca bien.

Sé explícito. En vez de "ejecutar los tests", mejor el comando completo con el fichero o el filtro, si viene al caso:

- Run all tests: `pnpm test`
- Run academy lessons tests only: `pnpm test:lessons`
- Skip e2e tests in CI fast-lane: `SKIP_E2E=1 pnpm test`

Paso 6: Documentar el estilo de código y las reglas de PR

El estilo de código es el terreno donde más lío arman las herramientas de IA cuando no está escrito. Comilla simple o doble. Punto y coma. Tabuladores o espacios. Funcional u orientado a objetos.

Escríbelo en concreto, con un ejemplo de sí y no cuando se pueda:

## Code style

- TypeScript strict mode, nada de `any`
- Solo comillas simples: `const x = 'hello'` y no `const x = "hello"`
- Sin punto y coma al final de las sentencias
- Async/await en vez de cadenas de `.then()`
- Named exports, nada de default export

El equipo de otra herramienta se puede ceñir a eso de inmediato. Con un "use clean code" a secas, más bien no.

Las reglas de PR deberían incluir: formato del título, comprobaciones obligatorias antes del commit, estrategia de merge. Si tienes un fichero de plantilla de PR, remite a él en vez de duplicar aquí la plantilla.

Paso 7: Ajustar CLAUDE.md para que nada esté por duplicado

Ahora el paso crítico. No quieres que AGENTS.md y CLAUDE.md se desvíen. Si los comandos de instalación cambian en AGENTS.md y CLAUDE.md sigue con los antiguos, te enteras en el siguiente fallo.

La solución limpia: que CLAUDE.md remita al principio a AGENTS.md.

# Claude Code Instructions

Lee primero @AGENTS.md, ahí están todas las reglas de instalación, tests y estilo.

Añadidos específicos de Claude Code:

- Capa de memoria: servidor MCP studiomeyer-memory
- Hooks: mira .claude/settings.json
- ...

El @AGENTS.md es una referencia propia de Claude Code que incluye el fichero. Así tienes el contenido una sola vez en un sitio y en CLAUDE.md solo añades lo que de verdad es específico de Claude Code (hooks, skills, montaje de memoria, notas del modo plan).

Más detalles en el playbook compañero Claude Code en equipo, mantener CLAUDE.md entre todos.

Paso 8: Fuente única de verdad o symlink

Si a tu equipo le resulta más sencillo, también puedes crear CLAUDE.md como symlink a AGENTS.md. Entonces técnicamente es el mismo fichero, y Claude Code lee CLAUDE.md, Codex lee AGENTS.md, y todos tienen la misma foto.

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md

Inconveniente: ya no puedes hacer añadidos específicos de Claude sin que sean visibles también para las demás herramientas. Si eso te encaja, es el camino más cómodo. Si no, quédate con dos ficheros separados y una referencia (paso 7).

En el repo de StudioMeyer decidimos no usar el symlink, porque nuestro CLAUDE.md contiene también indicaciones sobre hooks de memoria que a quien usa Cursor no le sirven de nada. Dos ficheros, bien separados, y AGENTS.md es el maestro.

Paso 9: Monorepo, un AGENTS.md por workspace

Si tienes un monorepo con workspaces de pnpm, Turborepo o Nx, te encuentras con que el AGENTS.md de la raíz por sí solo se vuelve demasiado genérico. Solución: por capas.

En la raíz: lo global.

# Monorepo Root

## Setup

- `pnpm install` en la raíz
- Apps en `apps/`, paquetes en `packages/`
- Cambia al workspace antes de construir nada: `cd apps/web`

En cada workspace un AGENTS.md propio con los comandos específicos del paquete.

# apps/web/AGENTS.md

## Setup

- `pnpm dev` arranca Next.js en el puerto 3000
- Migraciones de base de datos: `pnpm prisma migrate dev`

## Testing

- Tests unitarios: `pnpm test`
- e2e: `pnpm e2e` (necesita la base de datos en marcha)

La mayoría de herramientas de IA leen los dos. Primero el AGENTS.md más cercano, después el de la raíz como respaldo. Así tienes contexto justo donde el agente está trabajando, y evitas que el fichero de la raíz se hinche.

Paso 10: Qué sigue

Cuando AGENTS.md esté puesto, mantenerlo es sencillo. Con cada paso de instalación nuevo, cada comando de test que cambie, cada regla de lint nueva: al fichero, commit y listo. Es la misma disciplina que con el README, solo que con otro destinatario.

Tres temas de continuación que merecen la pena:

Si atiendes varias ramas en paralelo con Claude Code, ayudan los git worktrees. Una sesión de Claude por worktree, sin caos de stash. Mira Claude Code con git worktrees.

Si tu equipo anda tocando un CLAUDE.md compartido y eso provoca conflictos habituales en las revisiones de PR, mira Claude Code en equipo.

Y si quieres leer a fondo la especificación oficial de AGENTS.md, la entrada está en https://agents.md/ con ejemplos de más de 60.000 repos.

Un fichero. Varias herramientas. Menos explicaciones.