Cómo migrar de Claude Code a Augment Code sin perder el contexto (2026)

Cada archivo CLAUDE.md, sin cambios. La documentación de reglas de Augment enumera los archivos que Auggie carga "en el siguiente orden de precedencia":

1. Archivo de reglas personalizadas (a través del flag --rules), 2. CLAUDE.md, 3. AGENTS.md, 4. Directrices del espacio de trabajo (.augment-guidelines), 5. Carpeta de reglas del espacio de trabajo (<workspace_root>/.augment/rules/), 6. Carpeta de reglas del usuario (~/.augment/rules/)

Dos cosas llaman la atención. CLAUDE.md se sitúa por encima de AGENTS.md, que es lo contrario del orden que utilizan varios otros agentes. Y ambos nombres de archivo externos se sitúan por encima del directorio de reglas nativo de Augment, con el directorio a nivel de usuario en último lugar.

Los archivos CLAUDE.md anidados se transfieren y mantienen su alcance. Claude Code descubre archivos CLAUDE.md a lo largo del árbol y establece que "todos los archivos descubiertos se concatenan en el contexto en lugar de anularse entre sí", ordenados "desde la raíz del sistema de archivos hasta tu directorio de trabajo", por lo que "las instrucciones más cercanas a donde iniciaste Claude se leen al final".

Augment hace algo estructuralmente similar pero activado de manera diferente. Su documentación describe las reglas jerárquicas de esta manera: "Cuando trabajas en un archivo, Augment busca AGENTS.md y CLAUDE.md en el directorio del archivo", luego "sube por el árbol de directorios, buscando estos archivos en cada directorio padre", y "todas las reglas descubiertas se incluyen en el contexto de esa sesión de trabajo". La búsqueda "se detiene en la raíz del espacio de trabajo". Las reglas también se "almacenan en caché por sesión de conversación para evitar la inclusión de duplicados".

Así que un monorepo con src/frontend/CLAUDE.md y src/backend/CLAUDE.md se comporta aproximadamente como esperas. Cuando se trabaja en src/frontend/, se cargan ese archivo y sus padres; el archivo de backend no se carga.

Las importaciones no se transfieren. Claude Code admite importaciones @path dentro de CLAUDE.md, con una sutileza documentada: "El análisis de importaciones omite los bloques de código Markdown y el código delimitado", por lo que un @README envuelto en comillas invertidas se mantiene literal. La documentación de reglas de Augment describe archivos Markdown simples con frontmatter YAML opcional y no documenta una sintaxis de importación. Cualquier línea @path en un CLAUDE.md migrado debe tratarse como texto: aplana el contenido importado dentro del archivo antes de confiar en él.

Un tipo de regla no tiene destino en la CLI. Las reglas de espacio de trabajo de Augment toman un campo type con dos valores documentados, always_apply y agent_requested, y las extensiones de IDE exponen un tercero. La página de la CLI es explícita sobre esta brecha:

"Las reglas manuales no son compatibles con la CLI. Las reglas con type: manual en <workspace_root>/.augment/rules/ son omitidas por la CLI; no hay un mecanismo de mención con @ para adjuntarlas bajo demanda".

La página del lado del IDE lo repite: Manual es "solo para IDE: se adjunta bajo demanda mediante mención con @; la CLI lo omite". Si tu equipo ejecuta ambas interfaces, una regla manual estará activa en el editor y ausente en la terminal.

Las reglas a nivel de usuario pierden su frontmatter. Augment documenta que "las reglas de usuario en ~/.augment/rules/ siempre se tratan como always_apply y no admiten otros tipos de frontmatter". Cualquier cosa que pongas en tu directorio de inicio estará activa en cada sesión de cada proyecto, independientemente de lo que diga su frontmatter.

La memoria automática no se transfiere. Claude Code tiene dos sistemas de persistencia, y sus documentos los describen como complementarios: los archivos CLAUDE.md que escribes y la memoria automática —"notas que Claude escribe por sí mismo basándose en tus correcciones y preferencias"— almacenada por proyecto en ~/.claude/projects/<project>/memory/ e inyectada "en cada sesión (las primeras 200 líneas o 25 KB)". Augment también tiene un sistema de memoria, pero diferente: los Cosmos Experts almacenan "conocimiento acotado en el sistema de archivos virtual compartido (VFS)", la memoria de un Expert "pertenece a su equipo" y hay dos modelos documentados, simple y ruidoso. Ninguno lee los archivos del otro. Cubrimos el lado de Cosmos por separado en dirigir lo que recuerdan los Experts de Augment; esta guía trata sobre la capa de instrucciones, que es un mecanismo diferente con un ciclo de vida diferente.

Paso 1: Decide si CLAUDE.md seguirá siendo la fuente de verdad y comprométete con la respuesta

Tienes dos opciones coherentes, y el peor escenario es no elegir ninguna.

Opción A: mantener CLAUDE.md. Ocupa el segundo lugar, funciona y mantiene el repositorio legible por Claude Code para cualquiera que no haya cambiado. El costo es que las funciones nativas de Augment —frontmatter type por regla, archivos por regla que puedes revisar de forma independiente— no estarán disponibles, porque un solo CLAUDE.md no tiene frontmatter ni límites de archivo.

Opción B: convertir a .augment/rules/. Obtienes un archivo por regla, cada uno con su propio type, que es lo más cercano que tiene cualquiera de las dos herramientas a la carga condicional. El costo es el que nadie ve venir, y merece su propio párrafo.

El descubrimiento jerárquico de Augment cubre exactamente dos nombres de archivo. Su documentación establece: "Solo los archivos AGENTS.md y CLAUDE.md se descubren jerárquicamente", e inmediatamente después: "Los archivos en .augment/rules/ solo se cargan desde la raíz del espacio de trabajo, no desde subdirectorios".

Por lo tanto, convertir al formato nativo de Augment te cuesta el alcance por directorio. Tu src/frontend/CLAUDE.md se cargaba solo cuando se trabajaba en el frontend. El mismo contenido movido a .augment/rules/frontend.md se carga desde la raíz del espacio de trabajo para todo. El formato nativo del proveedor es, en este único eje, el menos acotable de los tres que admite.

La respuesta práctica para la mayoría de los equipos es una división: mantén los archivos CLAUDE.md anidados donde el alcance por directorio esté haciendo un trabajo real, y usa .augment/rules/ solo para reglas de todo el repositorio que necesiten un type diferente a siempre activo. No conviertas un archivo anidado solo para ordenar el árbol.

Cualquiera que elijas, verifícalo en lugar de asumirlo. La propia nota de consistencia de Claude Code es una buena razón para verificar: "si dos reglas se contradicen entre sí, Claude puede elegir una de forma arbitraria". Dos árboles de reglas cargándose a la vez es exactamente cómo obtienes contradicciones que no escribiste, y el mecanismo de resolución no es algo que puedas inspeccionar. Analizamos cómo auditar esa situación en el lado de Claude Code en reconciliar capas conflictivas de CLAUDE.md.

Paso 2: Vuelve a declarar tus reglas condicionales y verifica el presupuesto de caracteres

El mecanismo de Claude Code para la carga condicional es .claude/rules/ con el frontmatter paths, además de su propia nota de que las reglas sin paths "se cargan al inicio con la misma prioridad que .claude/CLAUDE.md". El mecanismo de Augment es el campo type.

Mapéalos deliberadamente. Una regla de Claude Code con alcance de ruta se convierte en un CLAUDE.md anidado en el directorio al que se aplica —preservando el alcance— o en una regla agent_requested cuya description establece cuándo se aplica. La guía de Augment favorece esto último cuando puedes escribir una buena descripción: "Usa agent_requested en lugar de always_apply si deseas optimizar el uso del contexto. Para estas reglas, el agente determinará si la regla es relevante para tu tarea actual". Ten en cuenta que description es obligatoria para agent_requested y realiza todo el trabajo de selección.

Luego verifica los presupuestos, porque Augment publica límites estrictos y Claude Code publica una recomendación. Claude Code te aconseja "apuntar a menos de 200 líneas por archivo CLAUDE.md", lo cual es una guía, no un límite. La sección de limitaciones de Augment es un límite estricto, con un comportamiento documentado en caso de desbordamiento:

"Las Directrices de Usuario están limitadas actualmente a un máximo de 24,576 caracteres. Las Directrices del Espacio de Trabajo + Reglas están limitadas a un máximo de 49,512 caracteres. Si superamos estos límites, se notificará al usuario en la aplicación y se aplicarán en orden de (reglas manuales, reglas siempre + automáticas, .augment-guidelines)".

Lee el orden en esa última cláusula. Cuando estás por encima del presupuesto, las reglas manuales se aplican primero y .augment-guidelines al final. Un equipo que ha estado tratando .augment-guidelines como el archivo canónico está tratando el elemento de menor prioridad bajo presión como canónico.

Un detalle más específico del IDE si parte de tu equipo usa las extensiones en lugar de la CLI: "Las directrices definidas en VSCode no se propagarán a los IDE de JetBrains y viceversa". Las Directrices de Usuario se almacenan en el almacenamiento local del IDE, por lo que no se comparten ni se controlan por versiones. Cualquier cosa que le importe a más de una persona pertenece al repositorio.

Ambas herramientas clasifican archivos. Ninguna almacena la razón por la que existe una regla.

Esa es la brecha que hace que esta migración sea riesgosa de una manera que los movimientos de archivos no lo son. Cuando decides que un CLAUDE.md anidado se convierta en una regla agent_requested, también decides qué dice su description, y la descripción determina si la regla se volverá a cargar alguna vez. Si la restricción original era "el módulo de pagos no debe usar el ayudante de reintento compartido, porque realiza un doble cargo en una ruta de falla específica", la regla sobrevive al movimiento pero la razón no, y la siguiente persona que lea una regla escueta sin justificación la eliminará.

MemoryLake conserva las justificaciones: la decisión, qué se intentó, por qué se rechazó y cuándo. Se sitúa fuera de ambos sistemas de instrucciones, por lo que los cambios de precedencia y las conversiones de formato no pueden reordenarlo. Comienza aquí.

Paso 1: Crea una clave API

Crea un espacio de trabajo para el repositorio y genera una clave API. Limítala al repositorio en lugar de a Claude Code o Augment, ya que el punto es que sobreviva a ambos.

Paso 2: Sube tus primeros recuerdos

Recorre tu árbol de CLAUDE.md antes de convertir cualquier cosa y registra por qué está allí cada regla no obvia. Agrega las correcciones que le has estado dando a Claude Code repetidamente; esas son las mismas correcciones que su memoria automática ha estado acumulando localmente y que no se trasladan. Luego agrega las decisiones tomadas durante la propia migración: qué archivos conservaste, cuáles convertiste y qué dejaste atrás deliberadamente.

Paso 3: Conecta tu IA y agentes

Conecta Auggie y mantén Claude Code conectado durante la transición. Ambos leen el mismo conjunto, por lo que una regla que aún no has portado sigue teniendo su razonamiento disponible para cualquier agente que alguien decida usar.

La trampa de "ya funciona" deja de costarte un mes. Sabes desde el primer día que CLAUDE.md ocupa el segundo lugar, por lo que tomas la decisión de conservar o convertir deliberadamente en lugar de descubrir más tarde que tus nuevos archivos .augment/rules/ han estado por debajo de un archivo que olvidaste.

Las conversiones dejan de perder el alcance por accidente. Una vez que sabes que solo AGENTS.md y CLAUDE.md se descubren jerárquicamente, "mover todo al formato nativo" deja de parecer una limpieza obvia.

El desbordamiento deja de ser invisible. Los límites de Augment vienen con un orden de aplicación documentado, por lo que un equipo cerca de los 49,512 caracteres sabe qué categoría se degrada primero en lugar de adivinar por qué una regla dejó de aplicarse.

Y el problema de la interfaz dividida recibe un nombre. Una regla manual que funciona en VS Code y se omite en la CLI no es un error que encontrarás leyendo tus archivos de reglas; es un comportamiento documentado que o bien diseñas para evitarlo o bien te sorprende.

Haz un inventario antes de convertir. Enumera cada archivo CLAUDE.md, AGENTS.md, .augment-guidelines y .augment/rules/ en el repositorio y escribe cuáles esperas que se carguen. Luego prueba una regla deliberadamente extraña de cada uno y observa cuál se aplica realmente. Esta es la forma más rápida de detectar el caso que describimos en por qué los agentes ignoran tus archivos de instrucciones.

Mantén los archivos anidados anidados. El alcance por directorio es gratuito en los dos formatos externos y no está disponible en el nativo. Ese es un incentivo inusual y favorece dejar tu árbol como está.

Escribe los campos description como condiciones de activación. Para las reglas agent_requested, la descripción es todo el mecanismo de activación. "Patrones de desarrollo y mejores prácticas de componentes de React" —el propio ejemplo de Augment— es mejor que un resumen del contenido de la regla.

Trata ~/.augment/rules/ como siempre activo y nada más. El frontmatter allí se ignora, por lo que cualquier cosa que pongas en tu directorio de inicio se aplica a cada proyecto que abras. Resérvalo para preferencias personales genuinas.

No confíes en la importación automática de Augment para encontrar todo. "Buscará archivos markdown, por ejemplo, archivos que terminen en *.md o *.mdx", lo cual es útil pero no es lo mismo que un manifiesto. Si una regla importa, colócala en algún lugar que nombre la lista de precedencia.

Recuerda que ninguna de las dos herramientas obliga a cumplir las reglas. Claude Code lo dice claramente: "Claude las trata como contexto, no como una configuración obligatoria", y recomienda un hook PreToolUse "para bloquear una acción independientemente de lo que decida Claude". Las reglas describen la intención. La aplicación obligatoria es una capa diferente, y eso es cierto en ambos lados de esta migración. La versión de este problema para las convenciones internas se cubre en hacer que Claude se ciña a tus convenciones.

La sorpresa en esta migración no es que algo se rompa. Es que nada lo hace, durante un tiempo. CLAUDE.md es el segundo en la lista de precedencia de Augment, por lo que tu capa de instrucciones sigue funcionando y el formato nativo de la herramienta se queda sin usar debajo de ella.

Las dos decisiones que vale la pena tomar a propósito: si CLAUDE.md sigue siendo la fuente de verdad y si algún archivo anidado se aplana en .augment/rules/, porque ese directorio se carga solo desde la raíz del espacio de trabajo. Hazlo bien y esta será una de las migraciones de agentes más baratas disponibles. Hazlo mal y pasarás semanas depurando reglas que nunca se cargaron, en una herramienta que había estado leyendo tus archivos antiguos todo el tiempo.