Un único archivo de instrucciones para Claude Code, Codex y Cursor en 2026

Para obtener información sobre el servicio, consulta la documentación de Ailoot.

¿Qué cambia cuando usas Claude Code, Codex y Cursor juntos?#

En el ejemplo descrito, Claude Code es la herramienta principal, mientras que Codex y Cursor se usan para tareas específicas. Mi CLAUDE.md tiene unas 250 líneas de instrucciones: qué leer y en qué orden, qué no se debe tocar, qué comandos usar para el despliegue y las reglas de formato de los commits. La primera vez que probé Codex CLI en el proyecto, no conocía ninguna de esas reglas: ejecutó git push --force, se puso a curiosear en .env y renombró archivos sin cuidado.

Primero copié CLAUDE.md a AGENTS.md a mano. Dos semanas después descubrí que el proyecto ya tenía cuatro versiones de las mismas instrucciones: en CLAUDE.md, AGENTS.md, .cursorrules y .windsurf/rules/. Todas diferían un poco. No es un problema de Claude ni de Cursor, sino la trampa básica de cualquier sistema con varias fuentes de verdad. Analizo este problema con más detalle en la guía sobre el trabajo con varios agentes.

En junio de 2026, la documentación sobre memoria de Claude Code de Anthropic ofreció una respuesta: un archivo compartido más una importación. Desde septiembre de 2026, Claude Code lee AGENTS.md por sí mismo si el proyecto no tiene un CLAUDE.md. Se necesita una importación cuando tienes reglas específicas para Claude. A continuación, explico cuándo basta con un único AGENTS.md, cómo configurar una importación y cómo separar las reglas compartidas de las específicas de Claude.

¿Claude Code lee AGENTS.md por sí mismo?#

Antes de septiembre de 2026, la respuesta era «no». Issue #6235, que solicitaba compatibilidad con AGENTS.md, llevaba abierto desde agosto de 2025 y se cerró el 17 de agosto de 2026. Durante todo ese tiempo, la documentación sobre memoria apuntaba a una única solución: crear un CLAUDE.md e incluir en él AGENTS.md como importación. A partir de la versión 2.1.277, la documentación dice otra cosa:

Los archivos que lee Claude Code dependen exactamente de cuáles haya en el proyecto:

Para esta comprobación, cuentan CLAUDE.md, .claude/CLAUDE.md y CLAUDE.local.md que estén en el directorio de trabajo y en cualquier directorio superior. Un ~/.claude/CLAUDE.md personal, un archivo corporativo administrado y las reglas de .claude/rules/ no cuentan: se cargan junto con AGENTS.md.

Si no hay ningún CLAUDE.md, Claude Code lee al inicio todos los archivos AGENTS.md y .claude/AGENTS.md del directorio de trabajo y de los directorios superiores, y carga un AGENTS.md de un subdirectorio cuando abre un archivo en ese subdirectorio. Las importaciones @path dentro de AGENTS.md también funcionan. Claude Code no lee AGENTS.local.md, AGENTS.override.md ni el contenido del directorio .agents/.

El inconveniente: también cuenta un CLAUDE.local.md personal. Si creas uno para guardar tus reglas sin confirmar, Claude Code dejará de leer AGENTS.md sin avisarte. El ajuste siguiente lo soluciona.

El comportamiento se puede cambiar en /config, en Project instructions:

Si quieres conservar CLAUDE.local.md sin perder AGENTS.md, selecciona claude-md-and-agents-md. No habrá lecturas duplicadas: si AGENTS.md ya está incluido mediante la línea @AGENTS.md o un enlace simbólico, Claude Code no lo carga por segunda vez, independientemente del ajuste.

Puedes comprobar si se ha detectado el archivo con el comando /memory: a partir de la versión 2.1.280, la ruta de AGENTS.md aparece en la lista. En las versiones anteriores a la 2.1.277 y en las sesiones en las que el plugin integrado agents-md está deshabilitado, Claude Code solo lee CLAUDE.md y no aparece el elemento Project instructions en /config. Antes de la versión 2.1.281, las sesiones a través de Amazon Bedrock y las sesiones con la telemetría desactivada se comportaban igual. También puede que AGENTS.md no se detecte en la primera sesión después de actualizar desde una versión anterior; funcionará a partir de la siguiente.

¿Qué significa esto para una configuración con un solo archivo? Si no tienes reglas específicas para Claude, puedes prescindir de CLAUDE.md: basta con AGENTS.md, que leerán Claude Code, Codex y Cursor. Si sí tienes reglas de ese tipo (modo de planificación para directorios de riesgo, skills, hooks), necesitas CLAUDE.md, y Claude Code dejará de leer AGENTS.md por sí mismo. En ese caso, incluye AGENTS.md en CLAUDE.md con la línea @AGENTS.md; esta configuración funciona igual que antes de septiembre. También es útil para las versiones antiguas de Claude Code. Lo explico con detalle más abajo.

¿Cómo se importa @AGENTS.md dentro de CLAUDE.md?#

Un ejemplo mínimo funcional de la documentación oficial:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Esto es lo que ocurre. La primera línea, @AGENTS.md, es una directiva de importación. Cuando Claude Code analiza CLAUDE.md al inicio de una sesión, encuentra esta importación e inserta en su lugar todo el contenido de AGENTS.md. A continuación aparece el encabezado ## Claude Code: es Markdown corriente, pero sirve como sección de «adiciones específicas de Claude». Debajo hay una regla que solo se aplica a Claude Code: usar el modo de planificación para los cambios en el directorio de facturación. Codex CLI o Cursor no abren este archivo; utilizan el AGENTS.md sin modificar.

Una cita de la documentación sobre el funcionamiento de las importaciones:

Algunos detalles prácticos:

• Rutas relativas y absolutas. @AGENTS.md es relativo al archivo que contiene la importación. @/Users/me/shared/rules.md o @~/.claude/personal.md son rutas absolutas. Uso @~/.claude/personal.md para las preferencias personales que no quiero incluir en el repositorio.
• Hasta cuatro niveles. AGENTS.md puede importar @docs/coding-style.md, y coding-style.md puede importar otro archivo, hasta llegar a cuatro niveles. Es suficiente para cualquier estructura real.
• Los acentos graves bloquean las importaciones. Si el texto dice `@README`, es solo una mención del nombre, no una importación. Esto resulta útil para explicar a los lectores cómo funcionan las importaciones sin activar ninguna.
• Autorización para archivos fuera del proyecto. Si una importación apunta fuera del directorio de trabajo, como @~/.claude/personal.md, Claude Code muestra por primera vez un diálogo con una lista de esos archivos. Si rechazas, las importaciones externas quedan desactivadas y el diálogo no vuelve a aparecer. @AGENTS.md en la raíz del proyecto no muestra ningún diálogo. Así se evita cargar accidentalmente en el contexto un archivo que no guarda relación.

Después de cambiar a esta configuración en el proyecto descrito, mi CLAUDE.md pasó de 250 líneas a 60: @AGENTS.md más cinco o siete reglas que solo se aplican a Claude Code (modo de planificación para directorios de riesgo, qué no tocar en el área de administración y cómo redactar los commits). Todas las reglas compartidas están en AGENTS.md, que leen Codex y Cursor.

¿Cuándo conviene elegir un enlace simbólico y cuándo una importación?#

La documentación muestra así la opción del enlace simbólico:

ln -s AGENTS.md CLAUDE.md

Y a continuación ofrece una advertencia clara sobre Windows:

Tabla comparativa:

En el proyecto descrito uso importaciones. Estas son las razones:

1. El equipo es mixto. Trabajo en Mac; en el ejemplo, el equipo está repartido aproximadamente a partes iguales entre Windows y Mac. Si aparece un enlace simbólico en el repositorio, quienes usan Windows sin el modo de desarrollador lo obtendrán como un archivo de texto normal que contiene una sola línea, AGENTS.md. Esto provoca errores extraños: a veces funcionan las reglas, a veces no, y no queda claro por qué.
2. Quiero reglas específicas para Claude. Debajo de @AGENTS.md, mi CLAUDE.md tiene una sección «Claude Code» con reglas: usar --effort high para tareas de arquitectura, ejecutar npm run build antes de git push y no llamar a /api/v1/deploy manualmente. Codex no entiende estos comandos.
3. Es más fácil depurar. Cuando algo va mal, abro CLAUDE.md y veo la importación y mis excepciones. Un enlace simbólico no indica que «esto se añadió aquí». Para obtener más información sobre cómo depurar los ajustes de Claude Code, consulta la guía del modo seguro.

Si no tienes reglas específicas para Claude, el enlace simbólico deja de ser necesario a partir de la versión 2.1.277: elimina CLAUDE.md y Claude Code leerá AGENTS.md por sí mismo. Conserva el enlace simbólico solo si alguien del equipo usa una versión anterior a la 2.1.277 y no puede actualizarla. Si tienes reglas específicas para Claude, una importación resulta más cómoda en nueve de cada diez casos.

¿Qué leen Codex, Cursor, Copilot, Windsurf y Gemini CLI?#

Un mapa de las siete herramientas principales (basado en la documentación oficial de cada herramienta):

¿Qué se deduce de esto? Si un repositorio tiene AGENTS.md (y un CLAUDE.md con una importación cuando hacen falta reglas específicas para Claude), cinco de las siete herramientas reciben instrucciones actualizadas automáticamente. Cursor y Windsurf tienen archivos nativos propios. Puedes dejarlos como están (AGENTS.md también lo leen) o añadir una importación @AGENTS.md, aunque su sintaxis es diferente y no siempre está admitida.

La estrategia más sencilla para un proyecto nuevo:

1. Pon todas las reglas compartidas en AGENTS.md: el 95 % de las reglas van ahí.
2. Crea CLAUDE.md si necesitas reglas solo para Claude: pon @AGENTS.md en la primera línea y añade debajo una sección con las reglas específicas de Claude. Si no hay reglas de ese tipo, CLAUDE.md es innecesario; Claude Code lee AGENTS.md por sí mismo desde la versión 2.1.277.
3. Conserva .cursor/rules/ para Cursor en los pocos casos en que necesites algo específico de Cursor (sus comandos @Codebase y @Docs).
4. Haz lo mismo con Windsurf: olvídate del antiguo .windsurfrules; usa .windsurf/rules/ solo cuando necesites patrones para su sintaxis.

Este enfoque ofrece el 80 % de los beneficios con el 20 % del trabajo. Por mi experiencia, al organizar equipos mixtos en «Antigravity», mantener más de dos fuentes de verdad (una compartida y otra específica de Claude) se vuelve engorroso. Si alguien del equipo añade una regla a .cursorrules y se olvida de AGENTS.md, una semana después Cursor y Codex discreparán.

¿Cómo incorpora /init de Claude Code un AGENTS.md existente?#

Anthropic describe /init así en su documentación:

¿Qué significa esto en la práctica? El repositorio descrito tenía un .cursorrules de cuando probé Cursor (unas 80 líneas) y un AGENTS.md de 120 líneas, preparado a mano. Cuando ejecuté claude /init, el comando tomó ambos archivos, eliminó las reglas duplicadas y preparó un CLAUDE.md limpio en un minuto. Después lo revisé e hice pequeños cambios: quité elementos obsoletos y añadí una estructura con encabezados. Fue más rápido que reescribirlo desde cero.

El modo interactivo, en el que /init también lee AGENTS.md, se activa mediante una variable de entorno:

CLAUDE_CODE_NEW_INIT=1 claude

Cuando se inicia /init, Claude hace una serie de preguntas aclaratorias: qué elementos configurar (CLAUDE.md, skills, hooks), qué stack usa el proyecto y qué comandos utilizar para las pruebas. Después, un subagent explora el código —lee package.json, README.md y los archivos de configuración— y completa las partes que faltan. Al final, muestra una propuesta que puedes editar antes de guardarla. Para saber más sobre cómo configurar Claude Code al iniciar un proyecto, consulta la guía aparte.

Ahora, el inconveniente. Si el proyecto ya tiene un AGENTS.md activo, /init creará a su lado un CLAUDE.md que contiene una copia de sus reglas. A partir de ese momento, Claude Code solo lee CLAUDE.md de forma predeterminada, así que vuelven a existir dos fuentes de verdad: tú actualizas AGENTS.md, mientras Claude sigue trabajando con la copia antigua. El comando /import hace algo parecido: añade a CLAUDE.md una copia de AGENTS.md que se crea una sola vez. Para mantener una única fuente, coloca la importación @AGENTS.md en la primera línea de CLAUDE.md después de ejecutar /init y elimina de CLAUDE.md todo lo que repita AGENTS.md.

/init es un buen punto de partida para un proyecto nuevo o uno que estés migrando desde Cursor o Copilot. No hace falta buscar en internet la «mejor plantilla de CLAUDE.md»: Anthropic ya tiene en cuenta el contenido del repositorio. Si el proyecto ya tiene un AGENTS.md activo y no hay reglas específicas para Claude, /init no hace falta: Claude Code leerá AGENTS.md por sí mismo.

¿Cómo separar las instrucciones compartidas de las específicas de Claude?#

Yo las separo siguiendo este principio. Reglas compartidas que van en AGENTS.md:

• Qué no tocar en el código. .env, node_modules, las carpetas prisma/migrations (solo mediante prisma migrate), .next/, .git/.
• Cómo nombrar las cosas. Ramas: feat/, fix/, chore/. Commits: prefijos feat:, fix:, docs: seguidos de una descripción breve. Archivos de componentes en kebab-case.
• Comandos de pruebas y lint. npm run build, npm run lint, npm test. Qué comando ejecutar antes de git push.
• Principios de arquitectura. Qué va en src/lib/, qué va en src/components/, dónde reside la lógica de negocio y dónde está la interfaz de usuario.
• Seguridad. No confirmar nunca secretos en el repositorio. Acceder a la base de datos de producción solo mediante prod-psql. Acceder a producción por SSH solo mediante el alias prod, no mediante root@IP.

Reglas específicas de Claude que van en CLAUDE.md (debajo de @AGENTS.md):

• Modo de planificación. Usar el plan mode para cambios en directorios de riesgo (por ejemplo, src/billing/).
• Nivel de esfuerzo. Usar --effort high para tareas de arquitectura y medium para las tareas rutinarias.
• Skills. Qué agentes de IA y skills ejecutar en cada situación. Por ejemplo: «al trabajar en una guía, ejecutar el skill build-masterskaya-guide».
• Memoria de Claude. Qué guardar en la memoria automática y qué poner en CLAUDE.local.md. Para obtener más información sobre la memoria de Claude, consulta la guía sobre Memory y CLAUDE.md.
• Hooks. Si .claude/settings.json tiene hooks configurados, describe en CLAUDE.md qué hacen (Codex y Cursor no los conocen ni necesitan conocerlos).
• Skills y comandos. Una lista de los comandos con barra que uso a menudo (/init, /cd, /memory, /plan).

La frontera no siempre está clara. Por ejemplo, «no ejecutar nunca git push --force en main» es claramente una regla compartida, así que va en AGENTS.md. En cambio, «al ejecutar git push en una rama urgente, usar primero el modo de planificación» es específico de Claude Code, así que va en CLAUDE.md. La prueba es: «Si mañana eliminara Claude Code y conservara solo Codex, ¿seguiría aplicándose esta regla?». Si la respuesta es sí, ponla en AGENTS.md. Si es no, ponla en CLAUDE.md.

¿Qué va en AGENTS.md y qué va en CLAUDE.md o .claude/rules?#

Si las reglas superan las 200 líneas, ha llegado el momento de dividirlas. La documentación de Anthropic recomienda intentar que cada archivo tenga unas 200 líneas, porque en los archivos CLAUDE.md largos Claude empieza a seguir las instrucciones con menos frecuencia sin avisar: parece que las lee, pero las respeta menos.

Esta estructura me funciona para un proyecto grande:

my-project/
├── AGENTS.md                    # 100-150 líneas, compartido
├── CLAUDE.md                    # 30-50 líneas: @AGENTS.md + reglas específicas de Claude
└── .claude/
    ├── CLAUDE.md                # alternativa al archivo raíz, mismo archivo
    └── rules/
        ├── api.md               # con paths: ['src/api/**']
        ├── components.md        # con paths: ['src/components/**']
        ├── testing.md           # sin paths, siempre activo
        └── security.md          # sin paths, siempre activo

Cada archivo de .claude/rules/ puede incluir frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude carga estas reglas solo cuando trabaja con archivos que coinciden con este patrón. Si modifica src/components/Button.tsx, las reglas de API no se añaden al contexto. Así, la ventana de contexto se dedica solo a lo pertinente. El directorio .claude/rules/ también funciona sin CLAUDE.md: si el proyecto solo contiene AGENTS.md, sus reglas se cargan junto con las de este archivo y no desactivan la lectura directa de AGENTS.md.

Cursor y Windsurf admiten el mismo enfoque mediante sus directorios .cursor/rules/ y .windsurf/rules/. El estándar AGENTS.md puede hacer referencia a esos directorios, pero la sintaxis entre herramientas todavía no es totalmente estable. Es más seguro mantener las reglas compartidas en AGENTS.md y duplicar las reglas asociadas a rutas en .claude/rules/ y .cursor/rules/; son casos específicos y poco frecuentes, no la mayoría de las reglas.

Ubicaciones útiles para CLAUDE.md (ordenadas de la más general a la más específica):

Un ~/.claude/CLAUDE.md de ejemplo podría contener dos reglas: «responde en el idioma preferido del usuario» y «escribe Ailoot exactamente de esta forma». Estas reglas se aplican a todos los proyectos, así que no hace falta duplicarlas en cada repositorio.

De estos cuatro niveles, solo un CLAUDE.md de proyecto y CLAUDE.local.md desactivan la lectura directa de AGENTS.md. Un ~/.claude/CLAUDE.md personal y una política administrada no interfieren: Claude Code los lee junto con AGENTS.md.

¿Qué debes hacer si AGENTS.md ya está desactualizado en tu proyecto?#

En el proyecto descrito, tenía un AGENTS.md de mayo de 2025: 180 líneas, muchas de ellas desactualizadas (mencionaba puntos de conexión de la API de Anthropic que habían cambiado, ejemplos con una sintaxis claude --tools que ya no existe y reglas sobre ~/.claude/projects/ basadas en una estructura obsoleta).

Este es el plan que seguí para actualizarlo:

1. Revisarlo con claude en modo de planificación. Abro el repositorio, ejecuto claude --safe-mode y pregunto: «Vuelve a leer AGENTS.md y sugiere una lista de elementos desactualizados o repetidos. No lo edites; limítate a enumerarlos». En dos minutos obtuve una lista de 23 elementos que revisar.
2. Eliminar los elementos claramente obsoletos. De los 23 elementos, 9 estaban claramente desactualizados: sintaxis de comandos, puntos de conexión y nombres de flags. Borré esas líneas.
3. Combinar duplicados. Otros 6 elementos repetían lo mismo con distintas palabras («no hagas push forzado», «no uses nunca --force», «evita git push -f»). Los combiné en una sola línea.
4. Añadir elementos nuevos. Añadí las cosas que había observado que Claude/Codex hacían mal con regularidad durante el mes anterior, siguiendo la regla «una línea por patrón de error». El resultado fueron 8 elementos nuevos.
5. Pedir una revisión final a un subagent. Solicité a Claude una revisión con la instrucción «encuentra contradicciones, ambigüedades y duplicados». Encontró tres formulaciones que podían ser más claras. Las corregí.

Al cabo de una hora, AGENTS.md tenía 110 líneas actualizadas y conocía personalmente cada una. Fue fácil crear a partir de él un CLAUDE.md de 30 líneas. Codex también se volvió notablemente más cuidadoso con las pruebas después; sospecho que algunas de sus decisiones «extrañas» se debían a que había estado siguiendo de buena fe instrucciones desactualizadas.

Principios fundamentales para mantener actualizado un AGENTS.md:

• Cada regla responde a un error recurrente. Si durante el mes no se me ocurrió ni una vez aplicar una regla, no merece la pena conservarla.
• Redacta las reglas como órdenes, no como teoría. «Usa dos espacios» es una regla. «El estilo del código debe ser limpio» no lo es.
• Los detalles concretos están por encima de las generalidades. «Ejecuta npm run build antes de git push» es una regla. «Prueba los cambios» no lo es.

¿Qué NO funciona en absoluto con esta configuración?#

Algunas cosas que aprendí por las malas durante seis meses trabajando con esta configuración:

1. El autocompletado de Cursor no usa AGENTS.md. Cuando Cursor sugiere cómo completar una línea en el editor, no lee AGENTS.md en tiempo real: hay un motor rápido independiente que se encarga de eso. Las reglas de AGENTS.md solo cuentan cuando haces una consulta en el chat de Cursor. Esto significa que escribir «no uses var, usa const» en AGENTS.md no afectará al autocompletado; tienes que configurarlo mediante ESLint o la configuración de TypeScript.

2. Los hooks de Claude Code en AGENTS.md no funcionan con Codex. Si .claude/settings.json tiene configurado un hook PreToolUse para bloquear una acción concreta, esa información solo es útil para Claude. Codex no conoce los hooks; para él, es como si «la herramienta decidiera por su cuenta». Tiene sentido escribir «no hagas X» en AGENTS.md y «hay un hook que bloquea físicamente X» en CLAUDE.md, debajo de la importación.

3. Copilot y .github/copilot-instructions.md. GitHub Copilot lee su propio archivo y sigue sin leer muy bien AGENTS.md. Si tu equipo usa Copilot activamente, añade un archivo .github/copilot-instructions.md aparte con una versión abreviada de las reglas, o usa extensiones de Copilot que conozcan AGENTS.md. Esto está cambiando rápidamente, así que la situación puede ser distinta dentro de tres a seis meses.

4. Git no registra un enlace simbólico como un cambio en CLAUDE.md. Si ejecutas ln -s AGENTS.md CLAUDE.md y actualizas AGENTS.md una semana después, Git solo mostrará un diff de AGENTS.md. Es normal, pero puede que quien revise el PR no se dé cuenta de que CLAUDE.md también se ha actualizado mediante el enlace simbólico. Solución: escribe explícitamente en la descripción del PR: «AGENTS.md actualizado; Claude Code ve el mismo archivo a través del enlace simbólico».

5. Las importaciones profundas son difíciles de depurar. Si AGENTS.md importa @docs/coding-style.md, que importa a su vez @docs/typescript.md, resulta difícil depurar los conflictos entre reglas. Limito las importaciones a un nivel (CLAUDE.md → AGENTS.md) y no las anido más. Anthropic ofrece un hook InstructionsLoaded que registra qué archivos se han cargado; es útil para depurar configuraciones por capas. Nota: el hook se activa cuando AGENTS.md se incluye mediante una importación o un enlace simbólico, pero no cuando Claude Code lo lee por sí mismo.

La configuración completa de programación con IA para una tarde: clon de IA + Second Brain + ingeniería de contexto.

Conoce Ailoot.