Cómo escribir AGENTS.md y CLAUDE.md: qué hacen 100 repos

¿Para qué sirven AGENTS.md y CLAUDE.md?

Un agente de programación empieza cada sesión sin conocer el proyecto. El archivo de reglas es donde escribes una sola vez lo que, si no, tendrías que explicar cada vez: los comandos de compilación y de test, las convenciones de código, la estructura de directorios, las cosas de las que dices «esto, nunca». Este artículo explica cómo escribir ese archivo: con qué nombre crearlo, qué poner dentro y qué longitud debe tener.

AGENTS.md no pertenece a una sola herramienta. Es un formato abierto que gestiona la Agentic AI Foundation, vinculada a la Linux Foundation, y según su propio sitio lo usan más de 60.000 proyectos de código abierto. Es un archivo Markdown plano, sin campos obligatorios. CLAUDE.md, en cambio, es el archivo que Claude Code lee al empezar cada sesión. También es Markdown plano, pero con algunas funciones propias: puede importar otros archivos (@ruta) y tener capas propias de cada usuario u organización.

Nosotros hacemos una herramienta que lee estos archivos a diario: diffox, al revisar un pull request, lee también el archivo de reglas del repositorio (cómo funciona lo contamos en otro artículo). Las mediciones que siguen son un subproducto de ese trabajo.

¿Qué archivo lee cada herramienta?

Hicimos la tabla siguiente el 13 de octubre de 2026 con la documentación de cada una de las cinco herramientas. Puede cambiar con las nuevas versiones; el nombre de cada herramienta enlaza a su fuente.

Fuente: la documentación de cada herramienta, 13 de octubre de 2026. La fila de Claude Code vale para la versión 2.1.277 y posteriores.

La tabla deja dos cosas claras. La primera: las cinco herramientas pueden leer AGENTS.md; Gemini CLI, con un ajuste, y Claude Code, si no tiene un CLAUDE.md al lado. La segunda: cada herramienta trata las subcarpetas a su manera. Codex combina todos los archivos desde la raíz hacia abajo, Copilot toma el más cercano y Claude Code solo carga el de una subcarpeta cuando se abre un archivo en ella.

El 18 de junio de 2026, Google dejó de dar servicio en Gemini CLI a los usuarios gratuitos y a los suscriptores de Google AI Pro y Ultra, y los dirigió a Antigravity CLI; con una clave de API de pago o una licencia de empresa puedes seguir usando Gemini CLI. El 28 de octubre de 2026 leímos la documentación de reglas de Antigravity. Lee un archivo llamado AGENTS.md o GEMINI.md sin necesidad de ningún ajuste. Carga el archivo de una subcarpeta en cuanto el agente lee o edita un archivo de esa carpeta. Combina los archivos que encuentra; si las reglas se contradicen, vale la de la subcarpeta. El límite es de 24 KB por archivo. CLAUDE.md no está entre los archivos que enumera la documentación; si tus reglas están en AGENTS.md, Antigravity también las lee.

AGENTS.md está más extendido que CLAUDE.md

Para ver qué archivo está más extendido elegimos un solo criterio: los 100 repositorios de GitHub con más estrellas, el 13 de octubre de 2026. Buena parte de la lista no es software que se compile (listas de recursos, libros, cursos). Como los repositorios se eligieron sin mirar si tenían archivo de reglas, dejamos la lista tal cual.

En 47 de los 100 repositorios hay en la raíz al menos uno de estos dos archivos. AGENTS.md está en 42 repositorios y CLAUDE.md en 24; en 5 hay CLAUDE.md sin AGENTS.md. Los archivos propios de las demás herramientas son menos frecuentes: el de Copilot está en 11 repositorios, la carpeta de reglas de Cursor en 4 y GEMINI.md en 3. El antiguo archivo .cursorrules sigue en 1; .windsurfrules y .clinerules no aparecen en ninguno.

Si se cuentan también los de las subcarpetas y los archivos de las demás herramientas, los repositorios con al menos uno de estos archivos llegan a 55.

Si están los dos archivos, Claude Code solo lee CLAUDE.md

Este es el punto que más a menudo se entiende mal. Durante mucho tiempo Claude Code no leyó AGENTS.md en absoluto, y todavía hoy muchas fuentes lo dicen. Lo lee desde la versión 2.1.277, pero con una condición: que no haya un CLAUDE.md (o un CLAUDE.local.md) en el directorio de trabajo ni en los superiores. Si están los dos, el comportamiento por defecto es leer solo CLAUDE.md.

En la práctica significa esto: si al lado hay un CLAUDE.md, la regla que añades a AGENTS.md no llega a Claude Code. Codex, en cambio, por defecto solo lee AGENTS.md. En ese caso tienes que mantener los dos archivos sincronizados a mano.

Un CLAUDE.local.md que añades para tus notas personales tiene el mismo efecto: mientras exista, Claude Code no lee AGENTS.md. Para que lea los dos, pon el ajuste «Project instructions» de /config en claude-md-and-agents-md.

En 19 de los 100 repositorios los dos archivos están juntos en la raíz. Miramos uno por uno cómo enlaza cada repositorio los dos archivos.

8 repositorios hacen que CLAUDE.md apunte directamente a AGENTS.md: 5 escribiendo @AGENTS.md en CLAUDE.md y 3 con un enlace simbólico. En n8n, AutoGPT, RustDesk y Clash Verge Rev, CLAUDE.md es una sola línea. En 2 repositorios, CLAUDE.md remite a AGENTS.md con una simple frase; según la documentación de Claude Code, el agente solo ve ese archivo si decide abrirlo. 3 repositorios mantienen el mismo texto en los dos archivos, y en 1 de ellos las dos copias ya no tienen el mismo número de reglas. En los 6 restantes, cada archivo tiene un texto distinto: ahí Claude Code y Codex leen instrucciones diferentes en el mismo proyecto.

Dos formas de hacer que CLAUDE.md apunte a AGENTS.md

Los datos apuntan en la misma dirección: guarda las reglas en un solo archivo y haz que el otro apunte a él. Deja el texto principal en AGENTS.md, que lo leen más herramientas, y ponle al lado este CLAUDE.md:

@AGENTS.md

## Claude Code
Aquí van tus notas solo para Claude Code.

La línea de importación carga AGENTS.md como parte de CLAUDE.md; debajo escribes solo las notas exclusivas de Claude Code. Si no tienes notas así, también sirve un enlace simbólico: ln -s AGENTS.md CLAUDE.md.

El enlace simbólico tiene dos inconvenientes. Quien clona el repositorio en Windows puede ver un archivo de texto de una línea en lugar del enlace. Y Claude Code se niega a escribir a través del enlace y edita el archivo original. Si alguien del equipo usa Windows, la línea de importación es más segura.

Tener solo AGENTS.md también es ya una opción, porque las versiones actuales de Claude Code lo leen directamente. Dejar el CLAUDE.md de una línea para las versiones antiguas no hace daño: Claude Code no carga dos veces el mismo archivo.

Qué ponen los repositorios populares en el archivo

Para ver qué se escribe en el archivo, miramos los encabezados de los 47 archivos que leímos. Si un archivo dedica un encabezado propio a un tema, contamos que trata ese tema.

El tema más frecuente son las reglas de commits y pull requests (29 archivos). Les siguen los comandos de instalación y ejecución (26), el estilo de código (26), la estructura de directorios (21), los tests (16) y la seguridad (7). Con independencia de los encabezados, 36 de los 47 archivos tienen un comando escrito en un bloque de código o en línea. Este recuento solo mira las palabras de los encabezados, así que es aproximado, pero el orden está claro: el agente quiere saber primero qué ejecutar y cómo, y cómo entregar el cambio.

Dos buenos ejemplos, de Kubernetes y AutoGPT

Los dos ejemplos están entre los archivos de este recuento. El AGENTS.md de Kubernetes tiene 38 líneas. Cada regla dice qué no hacer y qué hacer en su lugar; junto a cada comando está escrito para qué sirve:

## Constraints

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
…
## Commands

Run `make help` for all available targets. Common workflows:

```
make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package)
make test-integration WHAT=./test/integration/scheduler
make verify                                 # All verification checks
make update                                 # ALL generators and formatters
```

El AGENTS.md de AutoGPT tiene 92 líneas; recoge la estructura de directorios, el comando de test de cada parte y reglas medibles para los pull requests. Su CLAUDE.md, en cambio, es solo la línea @AGENTS.md: la forma de enlazarlos que recomendamos más arriba.

## Testing

- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
…
## Pull requests

…
- Keep out-of-scope changes under 20% of the PR.

Los dos archivos están escritos con frases que pueden comprobar tanto un agente como una persona: «no edites a mano el archivo generado, ejecuta make update» o «que los cambios fuera de alcance no pasen de una quinta parte del pull request». Las citas son del commit que leyó el recuento; «…» marca las líneas omitidas.

Una plantilla de AGENTS.md para empezar

Un esqueleto corto de AGENTS.md, hecho con los encabezados más frecuentes de los repositorios populares y con los dos ejemplos de arriba. Es solo un ejemplo; lo escribimos en inglés porque los agentes que leen estos archivos y la mayoría de los equipos trabajan en inglés. Cambia los comandos y las rutas por los de tu proyecto:

# Project name

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter api`
- Lint and format: `pnpm lint && pnpm format`

## Project structure
- `apps/web` - Next.js front end
- `packages/api` - API service

## Code style
- TypeScript strict mode. Never use `any`; use `unknown`.

## Testing
- Add or update the test that covers your change.

## Commits and pull requests
- Conventional commits: `feat(api): ...`
- Keep unrelated changes out of the pull request.

## Never
- Never hand-edit files under `generated/`. Run `pnpm generate`.
- Never commit secrets; read them from the environment.

Si usas Claude Code, ponle al lado el CLAUDE.md de una línea: @AGENTS.md. Cada línea de la plantilla es un comando o una regla comprobable; contar qué hace el proyecto le corresponde al README.

Cómo escribir una buena regla

Sobre qué poner en el archivo, el criterio más útil es el de la documentación de Claude Code: una instrucción tiene que ser lo bastante concreta para poder verificarla. En lugar de «formatea bien el código», «usa 2 espacios de sangría»; en lugar de «prueba tus cambios», «ejecuta npm test antes del commit». Estos seis puntos combinan ese criterio con lo que aprendimos al escribir nuestro propio archivo:

• Di al agente qué hacer. Una frase que dice «haz esto» o «nunca hagas esto» se puede comprobar; una presentación del proyecto, no. En 3 de los 47 archivos que leímos no hay ni una sola frase así; el archivo mediano tiene 10.
• Escribe el comando tal cual. De «ejecuta los tests» el agente no puede deducir qué comando quieres decir; si escribes pnpm test --filter api, ejecuta ese.
• Escribe al lado por qué existe la regla. En nuestro propio archivo, junto a cada regla está el fallo que llevó a escribirla. Una regla sin su motivo la borra el primero al que le estorba.
• No escribas lo que las herramientas ya controlan. Añadir al archivo una regla que ya comprueban el formateador y el linter gasta líneas; cuanto más largo es el archivo, peor se siguen las instrucciones.
• Escribe cada regla en un solo sitio. Si la misma regla está escrita en dos archivos, una se queda desfasada, y la que se desfasa es la del archivo que menos se lee.
• Añade una regla cuando un error se repita; bórrala cuando deje de valer. Escribe la regla cuando el agente cometa el mismo error por segunda vez. En Claude Code, /doctor prompt-audit lista las instrucciones desfasadas y las que se contradicen.

El primero de estos puntos importa directamente en diffox. Al revisar un pull request, diffox lee el archivo de reglas de la raíz del repositorio: primero AGENTS.md y, si no existe, CLAUDE.md. También sigue el enlace simbólico y la línea @AGENTS.md. Las frases que dicen qué hacer se las entrega a los agentes especializados como reglas de revisión. Así, una regla que se puede comprobar también le sirve a la revisión.

La mayoría de los archivos de reglas tiene menos de 200 líneas

Sobre la longitud, la documentación de tres herramientas da tres límites distintos. Claude Code apunta a menos de 200 líneas por archivo, porque un archivo largo consume más contexto y el agente sigue peor las instrucciones. Cursor recomienda menos de 500 líneas por regla. Codex deja de añadir archivos cuando los que ha combinado suman 32 KiB.

La mediana de los 47 archivos que leímos es de 92 líneas; el más corto tiene 4 y el más largo 1.017. De ellos, 14 superan las 200 líneas y 2, las 500. El número de archivos que superan por sí solos el límite de 32 KiB de Codex es 1.

En un monorepo, una subcarpeta tiene su propio archivo de reglas

Los repositorios grandes no meten todas las reglas en un solo archivo. De los 98 repositorios cuyo árbol pudimos leer entero, 27 tienen AGENTS.md o CLAUDE.md también en alguna carpeta distinta de la raíz: 278 archivos en total.

El archivo de una subcarpeta vale para los cambios que se hacen en esa carpeta: las reglas del frontend están en la carpeta del frontend, y las del backend, en el backend. El archivo raíz se queda corto y el agente solo carga las reglas del lugar donde trabaja.

Con qué frecuencia sirve esto lo vimos en una medición nuestra de septiembre de 2026: en 17 repositorios con un archivo de reglas en una subcarpeta, 202 de los 417 últimos pull requests fusionados modificaban al menos un archivo de una carpeta así.

Eso sí: cada herramienta trata las subcarpetas a su manera. Si escribes lo mismo de dos formas distintas en dos niveles, qué frase vale depende de la herramienta. No dejes frases que se contradigan.