Saltar al contenido

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)
  1. Qué es AGENTS.md
  2. Qué poner adentro
  3. Cómo lo lee Claude Code
  4. AGENTS.md y CLAUDE.md juntos: importar con @
  5. Escribirlo corto
  6. Errores comunes
  7. Preguntas frecuentes
  8. Checklist

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.

un AGENTS.md en la raíz, varios agentes que lo leenen la página de agents.mdCodexJulesCursorAmpFactory+ 16 más en la páginaAGENTS.mdcon un ajusteAider.aider.conf.ymlread: AGENTS.mdGemini CLI.gemini/settings.jsoncontext.fileNameClaude Code v2.1.277+si no hay CLAUDE.mdun archivo de Markdown, sin campos obligatoriosClaude Code no aparece en agents.md; el dato sale de su changelog

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.
  1. # AGENTS.md es solo el título; lo que cuenta es el nombre del archivo, no los encabezados.
  2. ## Proyecto dice qué es y dónde vive el código, para que el agente no explore a ciegas.
  3. ## Comandos son los que el agente correrá tal cual; si no están aquí, los adivina.
  4. ## Estilo son reglas que se pueden comprobar, como buscar un componente parecido antes de crear otro.
  5. ## Pruebas define cuándo una tarea está terminada y cierra la salida fácil de borrar el test.
  6. ## Seguridad lista lo que nunca debe hacer. Es contexto, no un bloqueo.
  7. ## Commits y PRs fija 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.

la plantilla de AGENTS.md, sección por sección# AGENTS.md## Proyectoqué es y dónde vive el código## Comandoslo que el agente corre, tal cual## Estiloreglas que se pueden comprobar## Pruebascuándo una tarea está terminada## Seguridadlo que nunca debe hacer## Commits y PRscómo entrega el trabajofrases concretas que el agente pueda comprobarplantilla de 28 líneas · Claude Code sugiere menos de 200 por CLAUDE.md

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 tieneClaude Code lee
AGENTS.md, y ningún CLAUDE.md ni CLAUDE.local.md en tu carpeta o más arribaTu AGENTS.md
AGENTS.md y un CLAUDE.md o CLAUDE.local.md en tu carpeta o más arribaSolo tus archivos CLAUDE.md
Un CLAUDE.md que importa AGENTS.mdTu 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.

qué archivo lee Claude Code al iniciar la sesión¿CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.mden tu carpeta o más arriba?nosílee AGENTS.mdy .claude/AGENTS.mden la sesión verás:no CLAUDE.md found;AGENTS.md loaded: …/AGENTS.md¿tu CLAUDE.md importacon la línea @AGENTS.md?sílee CLAUDE.md+ AGENTS.mdnosolo CLAUDE.mdsin AGENTS.mdel import sirve aunque Claude no lea AGENTS.md solovalor por defecto de Project instructions: claude-md-or-agents-md

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/`.
  1. @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.
  2. ## Claude Code abre la parte exclusiva de esta herramienta; lo que sirve a todos los agentes se queda en AGENTS.md.
  3. 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.md a un proyecto que solo usaba AGENTS.md. Cuenta como CLAUDE.md y apaga la lectura de AGENTS.md; pon Project instructions en claude-md-and-agents-md o 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 --version muestra 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.md a 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 all y 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

Luis Morales

Luis Morales

Desarrollador frontend y Shopify, EcomLabs

@luismoralesdev en Instagram

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

← Blog