Cómo migrar tu CLAUDE.md a AGENTS.md sin perder el contexto (2026)

El contenido de instrucciones simples se transfiere por completo. Los comandos de configuración, el estilo de código, las instrucciones de prueba, las convenciones de PR, las restricciones arquitectónicas; esto constituye la mayor parte de la mayoría de los archivos CLAUDE.md, y AGENTS.md es lo mismo: un archivo markdown de instrucciones sin frontmatter obligatorio.

El alcance siempre activo se transfiere, con una advertencia por herramienta. Las herramientas que lo leen tratan un AGENTS.md a nivel de raíz como siempre activo. Codex "lee los archivos AGENTS.md antes de realizar cualquier trabajo". Zed "admite AGENTS.md como el archivo de instrucciones principal para la guía de agentes a nivel personal y de proyecto". Cursor enumera AGENTS.md como una "Alternativa simple a .cursor/rules" con soporte para subdirectorios anidados. Devin "extraerá y actualizará automáticamente el Conocimiento (Knowledge) basándose en archivos especializados en tu base de código, incluyendo… CLAUDE.md y AGENTS.md ".

La delimitación por directorios se transfiere, pero la mecánica difiere. Ambos formatos admiten archivos por directorio. Claude Code sube por el árbol desde tu directorio de trabajo y concatena lo que encuentra, ordenado "desde la raíz del sistema de archivos hasta tu directorio de trabajo". Codex construye su cadena en la misma dirección: "Codex concatena archivos desde la raíz hacia abajo, uniéndolos con líneas en blanco. Los archivos más cercanos a tu directorio actual anulan la guía anterior porque aparecen más tarde en el prompt combinado". Los archivos AGENTS.md anidados de Cursor se "combinan con los directorios principales, teniendo prioridad las instrucciones más específicas".

Misma forma, tres cargadores diferentes. Las instrucciones anidadas funcionan; no asumas una semántica de precedencia idéntica.

Un archivo, cuatro cargadores diferentes

Vale la pena saberlo antes de consolidar: "lee AGENTS.md" significa algo ligeramente diferente en cada herramienta, y las diferencias deciden cómo estructuras el archivo.

Codex construye una cadena de instrucciones una vez por ejecución. Comienza con un archivo global en tu directorio de inicio de Codex, luego va desde la raíz del proyecto hacia abajo hasta tu directorio de trabajo, tomando como máximo un archivo por directorio, y los concatena de la raíz hacia abajo. También limita toda la cadena: "deja de agregar archivos una vez que el tamaño combinado alcanza el límite definido por project_doc_max_bytes (32 KiB por defecto)".

Cursor trata un AGENTS.md raíz como la alternativa sin configuración a .cursor/rules, con archivos anidados "combinados con directorios principales, teniendo prioridad las instrucciones más específicas".

Zed lo utiliza como el archivo de instrucciones principal tanto para el ámbito personal como para el del proyecto: ~/.config/zed/AGENTS.md a nivel personal, y un archivo de proyecto que "anula el AGENTS.md personal cuando entran en conflicto". Su cargador de proyectos toma el primer archivo que coincida de una lista, que es por lo que importan los archivos de reglas obsoletos.

Devin no lo carga como instrucciones en absoluto; "extraerá y actualizará automáticamente el Conocimiento (Knowledge) basándose en archivos especializados en tu base de código, incluyendo… CLAUDE.md y AGENTS.md ". Que ese Conocimiento llegue luego a una sesión depende de las descripciones de fijación (pinning) y de activación (trigger).

La conclusión práctica es la misma en los cuatro: mantén el archivo raíz corto y lleva los detalles específicos a archivos a nivel de directorio. Eso satisface simultáneamente el límite de Codex, la precedencia de Cursor y el comportamiento de anulación de Zed.

Un pequeño alivio mientras configuras esto: la importación @AGENTS.md no activa el diálogo de aprobación de importación externa de Claude Code. Ese diálogo aparece cuando una importación "se resuelve fuera de tu directorio de trabajo"; un AGENTS.md en la raíz del repositorio está dentro de él, por lo que la importación se carga sin preguntar.

Lo que no se transfiere: tres cosas, y son la razón por la que conservas CLAUDE.md en lugar de eliminarlo:

Importaciones @path. La sintaxis de importación de Claude Code no tiene equivalente en AGENTS.md.

CLAUDE.local.md. Notas personales, no confirmadas (uncommitted), añadidas después de CLAUDE.md en cada directorio. Sin contraparte.

Cualquier cosa que Claude Code haya escrito por sí mismo. La memoria autogenerada es específica de Claude por definición.

Dos caminos documentados. Elige según si necesitas contenido específico de Claude.

Paso 1: Mueve el contenido compartido a AGENTS.md

Crea AGENTS.md en la raíz de tu repositorio y mueve todo lo que sea independiente de la herramienta allí: configuración, pruebas, estilo, convenciones. Luego lee lo que queda en CLAUDE.md y clasifícalo: las instrucciones genuinamente específicas de Claude se quedan, todo lo demás se va.

Mientras estás aquí, elimina en lugar de migrar las partes que dejaron de ser ciertas. Una consolidación es la mejor oportunidad que tendrás para deshacerte del párrafo que describe un servicio que ya retiraste.

Si tu repositorio también tiene .cursorrules, .windsurfrules o .clinerules, incorpóralos también ahora. Varias herramientas leerán AGENTS.md de forma nativa, y el cargador de instrucciones de proyecto de Zed toma el primer archivo que coincida de una lista que incluye .rules, .cursorrules, .windsurfrules, .clinerules, .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md y GEMINI.md, por lo que dejar un .cursorrules obsoleto puede ocultar por completo tu nuevo AGENTS.md.

Paso 2: Conecta Claude Code al mismo archivo

Anthropic documenta dos formas. La versión de importación, que te permite mantener adiciones específicas de Claude:

@AGENTS.md

## Claude Code

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

Según los documentos, "Claude carga el archivo importado al inicio de la sesión y luego añade el resto". O el enlace simbólico, "si no necesitas añadir contenido específico de Claude":

ln -s AGENTS.md CLAUDE.md

Dos notas de verificación tomadas directamente de la documentación. "El comando no produce ninguna salida si tiene éxito. En tu próxima sesión, ejecuta /context y confirma que CLAUDE.md aparece bajo Memory files (Archivos de memoria)". Y en Windows, "crear un enlace simbólico requiere privilegios de Administrador o el Modo de desarrollador, así que utiliza la importación @AGENTS.md en su lugar".

Hay un atajo que vale la pena conocer si prefieres no clasificar a mano: /init "lee las reglas de Cursor, en .cursor/rules/ o .cursorrules, y las reglas de Copilot, en .github/copilot-instructions.md, e incorpora las partes relevantes en el CLAUDE.md generado. Con CLAUDE_CODE_NEW_INIT=1 configurado, /init también lee AGENTS.md, .devin/rules/, .windsurf/rules/ o .windsurfrules y .clinerules ". Ten en cuenta la dirección: esto genera un CLAUDE.md a partir de tus otros archivos, que es lo contrario de lo que quieres aquí, pero es la forma más rápida de ver todo lo que has acumulado en un solo lugar antes de clasificarlo.

Luego revisa tu presupuesto de tamaño. Codex "deja de agregar archivos una vez que el tamaño combinado alcanza el límite definido por project_doc_max_bytes (32 KiB por defecto)" y recomienda aumentar el límite o dividirlo en directorios anidados si lo alcanzas. La guía de Claude Code es que los archivos más largos consumen más contexto y reducen la adherencia. El objetivo es un solo archivo consolidado; un solo archivo consolidado enorme no lo es.

Consolidar te da un archivo en lugar de tres. No cambia aquello para lo que un archivo es bueno, y los archivos de instrucciones son buenos para dar dirección, no para albergar el razonamiento de tu proyecto.

Cada cargador mencionado anteriormente concatena el contenido siempre activo en el contexto en cada ejecución. Es exactamente por eso que existen los límites de tamaño. Así que las partes que más deseas que un agente conozca (por qué la arquitectura es como es, qué enfoques ya intentaste y descartaste, la restricción que hace que una decisión extraña sea correcta) son precisamente las partes que no pertenecen a un archivo que se envía con cada solicitud.

Eso es lo que alberga MemoryLake: el conocimiento duradero de tu proyecto en una capa de la que leen tus herramientas, de modo que AGENTS.md se mantiene corto y el razonamiento sigue estando disponible. La configuración consta de tres pasos.

Paso 1: Crea una clave de API

Inicia sesión en MemoryLake y crea una clave de API. Una sola credencial para todas las herramientas que conectes.

Paso 2: Sube tus primeras memorias

Mientras clasificas CLAUDE.md, encontrarás un tercer grupo que no pertenece a ninguno de los dos archivos. Escríbelos como entradas cortas, una afirmación cada una:

Decisiones con la restricción que las produjo. "Las escrituras pasan por la tabla outbox porque el proveedor de pagos reintenta sin claves de idempotencia". Una regla establece la primera mitad; solo esta versión evita que se vuelva a proponer la alternativa.

Enfoques ya descartados. La categoría de mayor valor y la que no existe en ningún lugar del repositorio.

Conocimiento entre repositorios. Vocabulario de dominio y estándares que se aplican a cada proyecto que posees. AGENTS.md es por diseño para cada repositorio; esto no.

Correcciones que has hecho más de una vez. Si lo has dicho dos veces, es una entrada que falta, y la razón debe ir al lado.

Paso 3: Conecta tu IA y agentes

Conecta las herramientas que utilizas. MemoryLake es accesible a través de MCP y de una API, por lo que los agentes nativos de MCP (Claude Code, Codex y OpenClaw entre ellos) se conectan apuntando al servidor MCP, mientras que otros asistentes leen la misma memoria a través de la API.

Tres límites honestos. MemoryLake no es un reemplazo para AGENTS.md; sigues queriendo ese archivo, y vale la pena hacer la consolidación anterior por sí sola. Solo contiene lo que tú o tus agentes escriben en él, por lo que el Paso 2 es manual. Y los archivos de instrucciones son contexto en lugar de una configuración forzada; una capa de memoria no cambia eso.

Un solo archivo, y se mantiene preciso. Tres copias desincronizadas se convierten en una, y las herramientas que leen AGENTS.md de forma nativa lo detectan sin necesidad de configuración por herramienta.

Claude Code sigue funcionando. La importación @AGENTS.md está documentada, es de una sola línea y es reversible. No tienes que elegir entre el estándar y tu configuración actual.

El límite de tamaño deja de ser un problema. 32 KiB es generoso para dar dirección e inadecuado para una base de conocimientos. Dividir esos trabajos es lo que te mantiene por debajo del límite.

Un archivo de reglas obsoleto no puede eclipsar al nuevo. Una vez que sabes que Zed toma el primer archivo que coincide de su lista, eliminar .cursorrules se convierte en parte de la migración en lugar de ser un misterio tres semanas después.

Una nueva herramienta no cuesta nada. La mayor parte de la lista ya lee AGENTS.md, y cualquier cosa que no lo haga lee una capa de memoria a través de MCP, el formato cubierto en compartir una memoria entre Cursor y Claude Code.

Coloca el contenido compartido en AGENTS.md y el contenido específico de Claude debajo de la importación. Ese es el patrón documentado y mantiene el diff legible.

Elimina .cursorrules y .windsurfrules una vez integrados. De lo contrario, un cargador de coincidencia única puede elegir el obsoleto.

Utiliza la importación, no el enlace simbólico, si tienes instrucciones específicas de Claude. Y en Windows, utiliza la importación en cualquier caso.

Verifica con /context. Confirma que CLAUDE.md aparece bajo Memory files (Archivos de memoria) en tu próxima sesión en lugar de asumirlo.

Manténlo por debajo de los límites y divídelo por directorio cuando crezca. El valor predeterminado de Codex es 32 KiB para toda la cadena; los archivos anidados son la forma documentada de mantenerse dentro de ese límite.

No pegues documentos en él. Haz referencia a ellos. Las copias quedan obsoletas a medida que cambia el código, la idea detrás de por qué los agentes ignoran los archivos de instrucciones que escribiste.

Confírmalo en git. Eso es lo que hace que la consolidación sea un activo del equipo en lugar de uno personal.

Mantén las razones fuera del archivo y en una capa recuperable. Dirección en AGENTS.md, argumentación en la memoria. Esa división es lo que permite que el archivo se mantenga lo suficientemente pequeño como para ser seguido realmente.

AGENTS.md ganó por ser aburrido: un archivo markdown abierto con un nombre predecible que más de 60k repositorios y la mayoría de los agentes principales ya leen. Consolidar en él elimina el problema de la desincronización de tres archivos, y Claude Code (la notable herramienta que lee CLAUDE.md en lugar de AGENTS.md) tiene un puente documentado de una sola línea en la importación @AGENTS.md, o un enlace simbólico si no tienes nada específico de Claude que añadir.

Lo que la consolidación no resuelve es la parte para la que los archivos de instrucciones nunca fueron diseñados. Cada cargador envía contenido siempre activo con cada solicitud, razón por la cual todos tienen límites de tamaño. Así que mueve las instrucciones compartidas a AGENTS.md, mantén las líneas específicas de Claude debajo de la importación, elimina los archivos de reglas obsoletos y coloca tus decisiones, restricciones y enfoques rechazados en una capa que tus agentes puedan consultar. Un archivo corto que se sigue supera a un archivo largo que se trunca.