Claude Code lee AGENTS.md: cómo escribirlo y combinarlo con CLAUDE.md
Actualización/ 10 min de lectura
Desde la 2.1.277, Claude Code lee AGENTS.md si no hay CLAUDE.md. Qué poner en el archivo, cómo se lee y cómo importarlo desde CLAUDE.md con una línea.
- Claude Code
- IA
En este artículo (8)
Desde la versión 2.1.277, publicada el 18 de septiembre de 2026, Claude Code lee AGENTS.md cuando tu proyecto no tiene CLAUDE.md. Si tienes los dos, lee solo CLAUDE.md, y desde ahí puedes importar AGENTS.md con la línea @AGENTS.md. Así un solo archivo de instrucciones sirve a varios agentes.
Qué dice cada fuente, con su fecha: la especificación en agents.md (leída el 12 de noviembre de 2026), el aviso de la versión 2.1.277 (18 de septiembre de 2026), el changelog de Claude Code, que incluye la 2.1.281 (23 de septiembre), y la documentación de memoria (leída el 12 de noviembre). No ejecutamos Claude Code para esto: lo que hace es lo que describe su documentación. Al final hay una plantilla de 28 líneas y el CLAUDE.md que la importa. Para mantener corto el CLAUDE.md, mira contexto para agentes de IA.
Qué es AGENTS.md
Según agents.md, es «un formato simple y abierto para guiar a agentes de código», un «README para agentes» (traducción nuestra). El README es para personas: arranque rápido, descripción del proyecto, cómo contribuir. AGENTS.md reúne lo que un agente necesita y estorbaría en el README: pasos de build, pruebas y convenciones. Es Markdown normal: la página responde que no hay campos obligatorios y que sirven los encabezados que quieras.
La especificación la mantiene ahora la Agentic AI Foundation, bajo la Linux Foundation, y dice que nació de la colaboración de OpenAI Codex, Amp, Jules de Google, Cursor y Factory. Su página mostraba 23 herramientas compatibles el 12 de noviembre, entre ellas Aider, Gemini CLI, Windsurf y el agente de código de GitHub Copilot, con un enlace a la lista completa. Claude Code no aparece en la página: que lea el archivo consta en su changelog y su documentación, no en agents.md. Dos herramientas se configuran con un ajuste: Aider con read: AGENTS.md en .aider.conf.yml, y Gemini CLI con "context": { "fileName": "AGENTS.md" } en .gemini/settings.json.
En un monorepo puedes poner otro AGENTS.md dentro de cada paquete: los agentes leen el más cercano en el árbol de directorios, y lo que le pidas directamente en el chat manda sobre todo.
Desliza la figura para verla completa
Qué poner adentro
agents.md sugiere secciones de resumen del proyecto, comandos de build y de pruebas, estilo de código, instrucciones de prueba y seguridad, y añade pautas de commits y PRs o pasos de despliegue: lo que le dirías a alguien nuevo en el equipo. Si listas los comandos de prueba, el agente intentará ejecutarlos y arreglar los fallos antes de terminar. Esta es la plantilla de la guía, para una tienda de ejemplo; cámbiala por tu proyecto:
# AGENTS.md
## Proyecto
- Tienda en Next.js con App Router y TypeScript estricto.
- Código en `src/`, rutas en `src/app/`, pruebas en `tests/`.
## Comandos
- Instalar: `npm ci`
- Desarrollo: `npm run dev`
- Pruebas: `npm test`
- Lint y tipos: `npm run lint` y `npx tsc --noEmit`
## Estilo
- Un componente por archivo, en PascalCase.
- Antes de crear un componente, busca uno parecido en `src/components/`.
- No agregues dependencias sin preguntar.
## Pruebas
- Corre `npm test` y `npm run lint` antes de dar una tarea por terminada.
- Si un test falla, arregla el código: no borres ni saltes el test.
## Seguridad
- No leas, imprimas ni edites archivos `.env*`.
- No hagas `git push` ni despliegues.
## Commits y PRs
- Commits pequeños, con el mensaje en imperativo.
- En la descripción del PR, lista los comandos que corriste y su resultado.
# AGENTS.mdes solo el título; lo que cuenta es el nombre del archivo, no los encabezados.## Proyectodice qué es y dónde vive el código, para que el agente no explore a ciegas.## Comandosson los que el agente correrá tal cual; si no están aquí, los adivina.## Estiloson reglas que se pueden comprobar, como buscar un componente parecido antes de crear otro.## Pruebasdefine cuándo una tarea está terminada y cierra la salida fácil de borrar el test.## Seguridadlista lo que nunca debe hacer. Es contexto, no un bloqueo.## Commits y PRsfija cómo entrega el trabajo.
Esa aclaración del punto 6 viene de la documentación de Claude Code: las instrucciones son contexto, no configuración que se haga cumplir, y para bloquear algo de verdad, como leer un .env, hace falta un hook PreToolUse. Revisar los cambios de un agente de IA muestra cómo hacer cumplir una regla con uno.
Desliza la figura para verla completa
Cómo lo lee Claude Code
Según la documentación de memoria, Claude Code puede leer AGENTS.md como instrucciones del proyecto sin CLAUDE.md, sin import y sin ajuste. Esto es lo que lee por defecto, según lo que haya en tu repositorio:
| Tu repositorio tiene | Claude Code lee |
|---|---|
| AGENTS.md, y ningún CLAUDE.md ni CLAUDE.local.md en tu carpeta o más arriba | Tu AGENTS.md |
| AGENTS.md y un CLAUDE.md o CLAUDE.local.md en tu carpeta o más arriba | Solo tus archivos CLAUDE.md |
| Un CLAUDE.md que importa AGENTS.md | Tu CLAUDE.md, con AGENTS.md incluido por el import |
Dos detalles que sorprenden. Primero, CLAUDE.local.md cuenta como CLAUDE.md: si lo agregas para tus preferencias personales en un proyecto que solo usa AGENTS.md, Claude deja de leer AGENTS.md. Segundo, no cuentan para esa comprobación tu ~/.claude/CLAUDE.md, el CLAUDE.md administrado de tu organización ni los archivos de .claude/rules/.
Al iniciar la sesión, Claude Code carga cada AGENTS.md y .claude/AGENTS.md de tu carpeta y de las de arriba; en una sesión interactiva verás una línea como no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md. El AGENTS.md de una subcarpeta se carga cuando Claude abre allí un archivo con Read y esa subcarpeta no tiene ningún CLAUDE.md. No lee AGENTS.local.md, AGENTS.override.md ni nada dentro de .agents/.
Para cambiar el comportamiento, escribe /config y ajusta Project instructions: claude-md-or-agents-md (el valor por defecto), claude-md-and-agents-md (lee los dos, CLAUDE.md primero), claude-md (solo CLAUDE.md) o managed-only.
Desliza la figura para verla completa
Actualizado el 12 de noviembre de 2026: después de la 2.1.277 cambió el alcance. La 2.1.281, del 23 de septiembre, extendió el soporte a Amazon Bedrock, Google Vertex AI, Microsoft Foundry, gateways de LLM y sesiones con telemetría desactivada; antes, esas sesiones leían solo CLAUDE.md. Y la documentación actual describe el valor claude-md-and-agents-md. Si tu versión es anterior a la 2.1.277, actualiza o usa el import de la siguiente sección. Y si acabas de actualizar desde la 2.1.276 o antes, la documentación dice que Claude lo lee desde tu siguiente sesión.
AGENTS.md y CLAUDE.md juntos: importar con @
Si el proyecto ya tiene un CLAUDE.md, o tu sesión no puede leer AGENTS.md directo, usa un import. La documentación lo plantea así: pon @AGENTS.md en un CLAUDE.md junto a él y escribe debajo lo que sea solo de Claude Code. Claude lee primero el archivo importado y luego el resto:
@AGENTS.md
## Claude Code
Usa plan mode para cambios en `src/checkout/`.
@AGENTS.md, en la primera línea, importa el archivo: se expande y carga junto al CLAUDE.md. La ruta es relativa al archivo que importa, y los imports pueden encadenarse hasta cuatro niveles.## Claude Codeabre la parte exclusiva de esta herramienta; lo que sirve a todos los agentes se queda en AGENTS.md.- La última línea es un ejemplo de instrucción solo para Claude Code. Cámbiala por la tuya.
Cuidado con la arroba: el análisis de imports se salta los fragmentos de código y los bloques cercados, así que para mencionar una ruta sin importarla, ponla entre comillas invertidas; un @README suelto fuera de ellas sí importa el archivo. Un import tampoco reduce el costo de contexto, porque el archivo importado se carga junto al CLAUDE.md. Y si Claude ya lee AGENTS.md por su cuenta, dejar el import es inofensivo: la documentación dice que nunca lo lee dos veces.
La alternativa es un enlace simbólico, ln -s AGENTS.md CLAUDE.md, con dos límites que da la documentación. Las herramientas Edit y Write se niegan a escribir a través del enlace y piden editar el destino. Y en Windows crear enlaces simbólicos exige permisos de administrador o Modo de desarrollador, y Git baja un enlace guardado como texto plano salvo que core.symlinks esté activo; si alguien de tu equipo usa Windows, usa el import. Con cualquiera de los dos, corre /context all en tu siguiente sesión y confirma que CLAUDE.md aparece en Memory files.
Escribirlo corto
La guía de la documentación apunta a menos de 200 líneas por archivo CLAUDE.md: los largos consumen más contexto y reducen la adherencia. La cifra es para CLAUDE.md, pero AGENTS.md entra al mismo contexto, así que es razonable aplicarla igual (inferencia nuestra, la página no lo dice). La misma guía pide instrucciones concretas y verificables («los manejadores de API viven en src/api/handlers/» en lugar de «mantén los archivos ordenados»), encabezados y viñetas, y nada contradictorio: si dos reglas chocan, Claude puede elegir una al azar. Y agents.md propone tratar el archivo como documentación viva, no como algo que se escribe una vez.
Errores comunes
- Tener un CLAUDE.md que no importa AGENTS.md. Claude Code lee solo CLAUDE.md y tu AGENTS.md queda fuera.
- Agregar
CLAUDE.local.mda un proyecto que solo usaba AGENTS.md. Cuenta como CLAUDE.md y apaga la lectura de AGENTS.md; pon Project instructions enclaude-md-and-agents-mdo importa el archivo. - Escribir «lee AGENTS.md» en palabras dentro de CLAUDE.md. Claude lo ve solo si decide abrir el archivo; usa el import.
- Copiar el mismo texto en los dos archivos. Se desfasan; deja uno y que el otro lo importe.
- Tratar las reglas de seguridad como un bloqueo. Son contexto; para impedir algo de verdad, un hook.
Preguntas frecuentes
¿Claude Code lee AGENTS.md sin que haga nada?
Sí, desde la 2.1.277, si no hay CLAUDE.md ni CLAUDE.local.md en tu carpeta de trabajo o más arriba. Comprueba tu versión con claude --version; en una sesión interactiva verás el aviso no CLAUDE.md found; AGENTS.md loaded.
Tengo AGENTS.md y CLAUDE.md: ¿cuál se lee?
Por defecto, solo los CLAUDE.md. AGENTS.md entra si tu CLAUDE.md lo importa con @AGENTS.md o si cambias Project instructions a claude-md-and-agents-md. Para las demás herramientas, agents.md dice que gana el AGENTS.md más cercano al archivo que se edita y que lo que escribes en el chat manda sobre todo.
¿Sirve un enlace simbólico?
Funciona: ln -s AGENTS.md CLAUDE.md. Pero las herramientas Edit y Write no escriben a través del enlace, y en Windows necesita permisos especiales o Modo de desarrollador. En equipos mixtos, el import es más seguro.
¿Cuánto debe medir?
La documentación apunta a menos de 200 líneas por CLAUDE.md; la plantilla de este artículo tiene 28. Si algo solo importa para una parte del código, la documentación sugiere reglas por ruta en .claude/rules/ en lugar de engordar el archivo.
Checklist
claude --versionmuestra 2.1.277 o posterior, o tienes el import en CLAUDE.md.- AGENTS.md está en la raíz, en Markdown simple, con comandos que el agente puede correr.
- Si hay CLAUDE.md, su primera línea es
@AGENTS.md. - No agregaste
CLAUDE.local.mda un proyecto que depende solo de AGENTS.md. - Menos de 200 líneas, sin reglas contradictorias.
- Lo crítico tiene un hook, no solo una línea de texto.
- Corriste
/context ally viste el archivo en Memory files.
Si quieres afinar qué entra al CLAUDE.md y qué no, lee contexto para agentes de IA. Y para convertir una línea de tus instrucciones en una regla que se cumple, mira cómo revisar los cambios de un agente.
¿Viste esto en Instagram? Comenta AGENTS en el Reel y te mando la guía.
Escrito por

Publicado el 12 de noviembre de 2026 · actualizado el 18 de noviembre de 2026