# Un único archivo de instrucciones para Claude Code, Codex y Cursor en 2026
> Una única fuente de verdad para Claude Code, Codex y Cursor en 2026: cuándo Claude Code lee AGENTS.md por sí mismo, cómo importar @AGENTS.md en CLAUDE.md, los enlaces simbólicos y /init.
Source: https://ailoot.ai/blog/es/agents-md-claude-md-one-instruction-file/
Canonical: https://ailoot.ai/blog/es/agents-md-claude-md-one-instruction-file/
Language: es
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-004
Revision: sha256-10e26768adaacd64c0f2e739d07eda1e2b988bf2b792735cca2e87a888ecc40f
Para obtener información sobre el servicio, consulta la [documentación de Ailoot](https://ailoot.ai/docs/).
## ¿Qué cambia cuando usas Claude Code, Codex y Cursor juntos?
Punto clave
En 2026, la configuración típica de quien programa por intuición con IA no consiste en una sola herramienta, sino en 3–5. Claude Code como herramienta principal, Codex para tareas autónomas largas y Cursor para cambios rápidos en el IDE. Cada una tiene su propio archivo de instrucciones: `CLAUDE.md`, `AGENTS.md`, `.cursorrules`. Si los mantienes sincronizados manualmente, editas una línea en cinco sitios, olvidas actualizar Cursor y, una semana después, Claude y Codex dan resultados diferentes para el mismo prompt.
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](https://ailoot.ai/blog/es/claude-code-codex-together/).
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?
Punto clave
Sí, a partir de la versión 2.1.277, publicada el 18 de septiembre de 2026, pero solo si no hay ningún `CLAUDE.md`, `.claude/CLAUDE.md` ni `CLAUDE.local.md` en el directorio de trabajo o en sus directorios superiores. Si existe un `CLAUDE.md`, Claude Code solo lee ese archivo de forma predeterminada, y `AGENTS.md` se incluye con la línea `@AGENTS.md` dentro de `CLAUDE.md` o mediante un enlace simbólico. El comportamiento se puede cambiar en `/config`, en Project instructions. Antes de septiembre, Claude Code no leía `AGENTS.md` en absoluto y la importación era la única opción.
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:
Claude Code puede leer AGENTS.md como instrucciones del proyecto, por lo que un repositorio ya configurado para otros agentes funciona sin CLAUDE.md, importación ni configuración.
— Anthropic, https://code.claude.com/docs/en/memory#agents-md
Los archivos que lee Claude Code dependen exactamente de cuáles haya en el proyecto:
| Archivos del proyecto | Qué lee Claude Code |
|----|----|
| `AGENTS.md`, sin `CLAUDE.md` ni `CLAUDE.local.md` en el directorio de trabajo o en sus directorios superiores | `AGENTS.md` |
| `AGENTS.md` y `CLAUDE.md` (o `CLAUDE.local.md`) en el directorio de trabajo o en sus directorios superiores | Solo `CLAUDE.md` |
| `CLAUDE.md` con la línea `@AGENTS.md` | `CLAUDE.md` y `AGENTS.md` dentro de este mediante la importación |
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:
| Ajuste | Qué lee Claude Code |
|----|----|
| `claude-md-or-agents-md` (predeterminado) | `CLAUDE.md` o, si no existen ni este ni `CLAUDE.local.md`, `AGENTS.md` |
| `claude-md-and-agents-md` | Ambos archivos: en cada directorio, primero `CLAUDE.md` y luego `AGENTS.md` |
| `claude-md` | Solo `CLAUDE.md` |
| `managed-only` | Solo el `CLAUDE.md` corporativo administrado y la memoria automática |
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?
Punto clave
Se necesita una importación cuando el proyecto tiene un `CLAUDE.md`: si existe, Claude Code no lee `AGENTS.md` por sí mismo de forma predeterminada. Para configurarla, escribe la línea `@AGENTS.md` al principio del archivo `CLAUDE.md`. Cuando Claude Code inicia una sesión, inserta el contenido de `AGENTS.md` en lugar de esa línea y lee el resultado como un solo texto. Debajo de la importación, puedes añadir una sección «Claude Code» con reglas que solo se aplican a Claude. Las importaciones funcionan con rutas relativas y absolutas y pueden anidarse hasta cuatro niveles.
Un ejemplo mínimo funcional de la documentación oficial:
```markdown
@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:
Los archivos CLAUDE.md pueden importar archivos adicionales mediante la sintaxis @path/to/import. Los archivos importados se expanden y se cargan en el contexto al iniciar la sesión junto con el CLAUDE.md que los referencia.
— Anthropic, https://code.claude.com/docs/en/memory
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?
Punto clave
Anthropic ofrece dos mecanismos: una importación mediante `@AGENTS.md` o un enlace simbólico, `ln -s AGENTS.md CLAUDE.md`. Un enlace simbólico es más sencillo: no es más que un alias y no requiere cambiar ningún archivo. Pero tiene tres inconvenientes: en Windows hace falta tener privilegios de administrador, no puedes añadir reglas específicas para Claude a `CLAUDE.md` y Git a veces muestra el enlace simbólico como algo inservible en el diff. La importación es la opción universal. Si no tienes reglas específicas para Claude, a partir de la versión 2.1.277 no necesitas ninguna de las dos: Claude Code leerá `AGENTS.md` por sí mismo.
La documentación muestra así la opción del enlace simbólico:
```bash
ln -s AGENTS.md CLAUDE.md
```
Y a continuación ofrece una advertencia clara sobre Windows:
Si tú o cualquier persona que clone el repositorio trabaja en Windows, utiliza la importación `@AGENTS.md`. Allí, crear un enlace simbólico requiere privilegios de administrador o el modo de desarrollador. Además, si `core.symlinks` no está activado en Git, un enlace confirmado en el repositorio se obtiene como un archivo de texto normal, de modo que el `CLAUDE.md` de esa copia contiene una sola línea en lugar de las instrucciones.
— Anthropic, https://code.claude.com/docs/en/memory
Tabla comparativa:
| Criterio | Importación `@AGENTS.md` | Enlace simbólico `ln -s` |
|----|----|----|
| **Funciona en Windows sin privilegios de administrador** | sí | no (se requiere el modo de desarrollador) |
| **Permite añadir reglas solo para Claude** | sí, debajo de la importación | no, el archivo es idéntico |
| **Aparece en Git como Markdown normal** | sí | como enlace (depende de `core.symlinks`) |
| **Permite importar varios archivos** | sí, hasta cuatro niveles | no, una relación de uno a uno |
| **Caché e invalidación en Claude Code** | estándar para CLAUDE.md | funciona, pero los enlaces simbólicos tienen inconvenientes con los metadatos |
| **Opción predeterminada** | adecuada para todos | solo si no importa la compatibilidad multiplataforma |
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](https://ailoot.ai/blog/es/claude-code-safe-mode-recovery/).
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?
Punto clave
Cada herramienta lee su propio archivo, a veces más de uno. Claude Code lee `CLAUDE.md` y, desde septiembre de 2026, también lee `AGENTS.md` si el proyecto no tiene un `CLAUDE.md`. Codex CLI lee `AGENTS.md` y `AGENTS.override.md`. Cursor lee el formato antiguo `.cursorrules` o el nuevo `.cursor/rules/*.mdc` y, desde el verano de 2026, también lee `AGENTS.md`. Copilot lee `.github/copilot-instructions.md` o `.github/instructions/*.instructions.md`. Windsurf lee el antiguo `.windsurfrules` o el nuevo `.windsurf/rules/`. Gemini CLI lee `GEMINI.md`. Aider y Cline ya han adoptado `AGENTS.md`.
Un mapa de las siete herramientas principales (basado en la documentación oficial de cada herramienta):
| Herramienta | Archivo principal de instrucciones | Alternativas | ¿Lee AGENTS.md? |
|----|----|----|----|
| **Claude Code** | `CLAUDE.md` | `~/.claude/CLAUDE.md`, `./.claude/CLAUDE.md`, política administrada | sí, si el proyecto no tiene `CLAUDE.md` (desde la 2.1.277); si no, mediante una importación |
| **Codex CLI** (OpenAI) | `AGENTS.md` | `AGENTS.override.md` | sí (de forma nativa) |
| **Cursor** | `.cursor/rules/*.mdc` | `.cursorrules` (obsoleto) | sí |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `.github/instructions/*.instructions.md` | mediante extensiones |
| **Windsurf** | `.windsurf/rules/` | `.windsurfrules` (obsoleto) | sí |
| **Gemini CLI** | `GEMINI.md` | \- | no |
| **Aider, Cline, opencode** | `AGENTS.md` | \- | sí (de forma nativa) |
¿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?
Punto clave
`/init` crea un `CLAUDE.md` a partir de lo que ya hay en el repositorio y ahorra 20–30 minutos de trabajo manual. De forma predeterminada, incorpora las reglas de Cursor (`.cursor/rules/`, `.cursorrules`) y las de Copilot (`.github/copilot-instructions.md`), mientras que lee `AGENTS.md`, `.windsurfrules` y `.clinerules` en el modo `CLAUDE_CODE_NEW_INIT=1`. Este mismo modo inicia un flujo interactivo en varias fases: hace preguntas, explora el código mediante un subagent y propone un plan antes de escribir. Desde septiembre de 2026, `/init` tiene un inconveniente en los proyectos con `AGENTS.md`: un nuevo `CLAUDE.md` desactiva la lectura directa de `AGENTS.md` y las reglas acaban en dos archivos.
Anthropic describe `/init` así en su documentación:
Al ejecutarlo, /init lee los archivos de instrucciones de otras herramientas y traslada las partes pertinentes al CLAUDE.md generado: las reglas de Cursor de .cursor/rules/ o `.cursorrules`, las de Copilot de `.github/copilot-instructions.md` y, con `CLAUDE_CODE_NEW_INIT=1`, también `AGENTS.md`, `.devin/rules/`, `.windsurf/rules/` o `.windsurfrules`, y `.clinerules`.
— Anthropic, https://code.claude.com/docs/en/memory
¿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:
```bash
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](https://ailoot.ai/blog/es/spec-kit-claude-code-spec-driven-development/).
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?
Punto clave
Pon en `AGENTS.md` las reglas que cualquier agente de IA pueda entender: qué no debe tocar, cómo nombrar las ramas, que `.env` contiene un secreto y qué comandos usar para las pruebas. Pon en `CLAUDE.md` (debajo de la importación) las reglas específicas de Claude Code: modo de planificación, skills, hooks, referencias a skills y nombres de modelos según la versión. La distinción es sencilla: si una regla empieza por «Claude debe», va en `CLAUDE.md`. Si empieza por «la herramienta debe», va en `AGENTS.md`.
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](https://ailoot.ai/blog/es/claude-memory-claude-md-auto-memory/).
- **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?
Punto clave
En un proyecto grande, un solo `AGENTS.md` no basta: crece demasiado y cada agente incorpora contenido innecesario a su contexto. La solución es un directorio `.claude/rules/` con archivos separados por tema y un frontmatter YAML `paths:` para activar reglas según la ruta. Por ejemplo, una regla de API solo se aplica cuando Claude trabaja en `src/api/`. Así se ahorra mucho espacio en la ventana de contexto. El equivalente para Cursor es `.cursor/rules/`, y para Windsurf, `.windsurf/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:
```markdown
---
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):
| Nivel | Ubicación | Propósito |
|----|----|----|
| **Política administrada** | `/Library/Application Support/ClaudeCode/CLAUDE.md` (Mac), `/etc/claude-code/CLAUDE.md` (Linux) | Normas corporativas, IT/DevOps |
| **Usuario** | `~/.claude/CLAUDE.md` | Preferencias personales para todos los proyectos |
| **Proyecto** | `./CLAUDE.md` o `./.claude/CLAUDE.md` | Reglas del equipo del proyecto |
| **Local** | `./CLAUDE.local.md` (en `.gitignore`) | Preferencias personales para un proyecto concreto |
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?
Punto clave
Si `AGENTS.md` se preparó en 2025 para Codex o Aider y no se ha editado desde entonces, abre el proyecto en Claude Code y pídele a Claude que edite el archivo. AGENTS.md es un documento vivo; la especificación de la Linux Foundation se actualiza. La regla principal para mantenerlo al día es que cada instrucción debe responder a la pregunta «¿Qué estoy cansado de repetirle a Claude/Codex?». Si no responde a esa pregunta, archívala.
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?
Punto clave
Importar `@AGENTS.md` no hace que las distintas herramientas se comporten igual. Cada una tiene sus peculiaridades: Codex CLI no conoce `.claude/rules/` ni los hooks. Cursor tiene su propio motor de autocompletado, que no lee CLAUDE.md mientras completa texto. Copilot sigue `.github/copilot-instructions.md`, y las reglas que solo están en AGENTS.md no le bastan. No es «un archivo = un comportamiento», sino «una fuente para las reglas básicas y, después, añadidos propios de cada herramienta».
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](https://github.com/marketplace?type=apps&category=copilot-extensions) 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.
### Fuentes
- [Documentación de Claude Code sobre memoria: sección AGENTS.md](https://code.claude.com/docs/en/memory#agents-md) - cuándo Claude Code lee AGENTS.md por sí mismo, ajustes de Project instructions, importaciones y enlaces simbólicos, y comportamiento de `/init`.
- [Documentación de Claude Code sobre memoria: importar archivos adicionales](https://code.claude.com/docs/en/memory#import-additional-files) - sintaxis `@path/to/file`, profundidad de cuatro niveles y rutas relativas y absolutas.
- [agents.md - estándar de la Linux Foundation](https://agents.md/) - estándar oficial de AGENTS.md y lista de herramientas compatibles.
- [Documentación de las reglas de Cursor](https://docs.cursor.com/context/rules-for-ai) - qué lee Cursor (`.cursor/rules/*.mdc`, AGENTS.md).
- [Instrucciones personalizadas de GitHub Copilot](https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot) - formato de `.github/copilot-instructions.md`.
- [Especificación de AGENTS.md de la Linux Foundation](https://aaif.io/projects/agents-md/) - especificación viva.
La configuración completa de programación con IA para una tarde: **clon de IA + Second Brain + ingeniería de contexto**.
Conoce [Ailoot](https://ailoot.ai/).
## Preguntas sobre Claude Code, AGENTS.md, Codex y Cursor
### ¿Cuándo uso una importación en lugar de un enlace simbólico?
Usa `@AGENTS.md` en `CLAUDE.md` si necesitas añadidos específicos de Claude o tus compañeros utilizan Windows. Un enlace simbólico hace que ambos nombres apunten al mismo contenido y no permite una sección separada exclusiva de Claude.
### ¿Cómo compruebo que se cargaron las instrucciones compartidas?
Ejecuta `/memory` y revisa los archivos de instrucciones listados. Si `CLAUDE.md` o `CLAUDE.local.md` impide la carga directa de AGENTS.md en tu configuración, añade la importación o elige cargar ambos. Después abre una sesión nueva.
## Ailoot · La empresa y su cartera de proyectos
Ailoot se apoya en la experiencia operativa acumulada, una amplia base de clientes, un servicio estable y el seguimiento continuo de KPI.
La empresa y su cartera de proyectos: millones de clientes; ventas por miles de millones al mes.
Ailoot aplica esa experiencia operativa al acceso por API a funciones de IA en productos de clientes, agentes, aplicaciones y automatizaciones.