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

El contenido de las reglas se transfiere casi textualmente. Las reglas de Windsurf son instrucciones para un modelo escritas en Markdown. Claude Code lee CLAUDE.md. No se necesita ninguna capa de traducción: estás cambiando dónde reside el texto, no lo que dice.

Vale la pena conocer la forma de lo que estás recopilando, ya que cambió a lo largo de la vida de Windsurf. La documentación de la comunidad describe la coexistencia de dos sistemas: el archivo de texto plano heredado `.windsurfrules` en la raíz del proyecto, y el directorio más nuevo `.windsurf/rules/` de reglas Markdown con alcance específico, prefiriendo las compilaciones actuales de Devin Desktop .devin/rules/ y manteniendo .windsurf/rules/ como alternativa. Se informa que las reglas en esos archivos están limitadas a aproximadamente 12,000 caracteres combinados, algo que vale la pena verificar en tu propia instalación, ya que estos detalles provienen de guías prácticas en lugar de una referencia oficial actual.

Ese comportamiento alternativo es la razón por la que esta migración parece opcional. Tus reglas antiguas se siguen leyendo, por lo que nada se degrada visiblemente y el inventario nunca se realiza.

Las memorias de Cascade no se transfieren, y esta es la pérdida real. La distinción que importa, como señalan las guías de la comunidad: las reglas son instrucciones estáticas que escribes y confirmas en el control de versiones, mientras que las memorias de Cascade son autogeneradas y locales; el agente registra el contexto de una sesión para dejar de volver a preguntar, pero las memorias no se comparten con los compañeros de equipo y no son un lugar para colocar convenciones deliberadas.

Lee eso con atención, porque funciona en ambos sentidos. Significa que Windsurf sí tenía una capa de memoria y estaba haciendo un trabajo real por ti: cada momento de "eso ya lo sabe" que dejaste de notar. También significa que la capa se generaba automáticamente a partir de las sesiones, era privada para una sola máquina y nunca se diseñó para ser exportada. No hay ningún archivo que puedas entregar a Claude Code.

Las conexiones MCP deben volver a agregarse, no convertirse. Sobrevivieron al cambio de marca de Windsurf a Devin automáticamente; no te siguen a un editor diferente. Claude Code admite servidores MCP, por lo que se trata de volver a ingresar la configuración en lugar de reescribir nada, pero las credenciales y las variables de entorno que necesitaba cada servidor vuelven a ser tu problema.

Las extensiones, los atajos de teclado y tu plan no se transfieren en absoluto. Esos se mantuvieron en el cambio de marca porque era el mismo editor. Claude Code es una CLI, no una bifurcación de VS Code, por lo que esta parte no es una migración: es un cambio de categoría de herramienta, y vale la pena mencionarlo de antemano para que no te sorprendas.

Los scripts y la automatización necesitan una auditoría. El cambio de marca movió .windsurf/tools/ a .devin/tools/, y el resumen ampliamente reportado de esa transición fue que el editor se migró a sí mismo pero los scripts no. Cualquier cosa que hiciera una llamada al sistema a una ruta de Windsurf ya es una rotura latente, y mudarse a Claude Code es un buen momento para encontrarla en lugar de una nueva causa de ella.

Paso 1: Recopila tus reglas y reconstruye lo que contenían las memorias

Comienza con los archivos, porque esa parte es mecánica. Busca en la raíz del proyecto .windsurfrules, luego en .windsurf/rules/ y .devin/rules/ para encontrar archivos Markdown con alcance específico. Recopílalos todos, incluidos los que habías olvidado que estaban allí; el límite combinado de caracteres significa que las reglas más antiguas a menudo se recortaban en lugar de eliminarse, y las reglas a medias son peores que ninguna.

Clasifica lo que encuentres por su alcance real:

• Global para tu trabajo — cómo quieres que se formatee la salida, los lenguajes y versiones predeterminados, cosas que se aplican a todos los proyectos.
• Global para este repositorio — convenciones, restricciones de arquitectura, requisitos de prueba.
• Específico de un área — reglas que solo se aplican a la capa de API, la capa de datos, las pruebas.

Luego haz la parte que no es mecánica. Abre Cascade (o Devin Desktop) y lee lo que el agente parece saber que no está escrito en ningún lado. La forma práctica de sacarlo a la luz es preguntar directamente: qué convenciones está siguiendo, qué se le ha dicho sobre este proyecto, qué evita hacer. Debido a que las memorias se generan automáticamente a partir de las sesiones, las respuestas suelen ser cosas que le dijiste una vez de pasada y que nunca escribiste: una peculiaridad de un proveedor, un directorio que no se debe tocar, un paso de compilación que debe ejecutarse primero.

Escribe eso como texto ordinario. Esta es la única hora insustituible en la migración; todo lo demás es copiar archivos. También es el momento de notar cuánta de la utilidad de tu editor se había acumulado en un almacenamiento local, por máquina, del que nunca hiciste una copia de seguridad.

Paso 2: Reconstruye las reglas como CLAUDE.md en los niveles adecuados

Claude Code lee CLAUDE.md, y la ubicación se encarga de definir el alcance:

• Las preferencias globales van en ~/.claude/CLAUDE.md.
• Las convenciones del repositorio van en CLAUDE.md en la raíz del proyecto, confirmadas en el control de versiones, para que tu equipo también las reciba.
• Las reglas específicas de un área van en un CLAUDE.md en ese subdirectorio, o se quedan en un documento al que hagas referencia.

Un hábito útil para el tercer caso: en lugar de incluir en línea una regla larga específica de un área, mantenla como un archivo en docs/ y coloca una sola línea en el CLAUDE.md raíz que apunte a ella: "read docs/api-conventions.md before touching anything under src/api/" (lee docs/api-conventions.md antes de tocar cualquier cosa bajo src/api/). También puedes importar archivos específicos con importaciones @path cuando sean relevantes en lugar de hacerlo siempre.

Si prefieres no empezar desde un archivo en blanco, /init genera un borrador de CLAUDE.md a partir del repositorio, y /memory abre los archivos de memoria para editarlos directamente. Ambos métodos son más rápidos que escribir desde cero, y ambos producen algo que luego deberías recortar.

Mantenlo corto. Todo lo que está dentro del alcance se carga en cada tarea, por lo que un archivo raíz largo es un costo que pagas en cada solicitud para siempre y, a diferencia del límite combinado de caracteres de Windsurf, nada te impide hacerlo demasiado largo. El límite te estaba haciendo un favor.

Luego establece las expectativas correctamente, porque aquí es donde la gente se decepciona. Los archivos de reglas hacen que el conocimiento esté disponible; no hacen que la herramienta recuerde. Claude Code comienza cada sesión de cero a partir de tus archivos y compacta el contexto en sesiones largas, razón por la cual it forgets your project context between sessions (olvida el contexto de tu proyecto entre sesiones) incluso con un buen CLAUDE.md, y por qué corrections you gave last week can come back undone (las correcciones que hiciste la semana pasada pueden volver a deshacerse). Has movido las reglas. No has reemplazado la capa de memoria autogenerada que acabas de perder, y Claude Code no incluye una.

Observa la forma de lo que acaba de suceder. Perdiste una capa de memoria porque era local para una máquina y estaba soldada a un producto, y el producto cambió debajo de ti: primero con el cambio de marca, luego al poner fin al agente que usabas.

Eso no es un fallo de Windsurf. Es lo que le sucede a cualquier conocimiento que vive dentro de una herramienta: es excelente hasta que la herramienta cambia, y luego es irrecuperable. Las memorias de Cascade eran autogeneradas y locales por diseño; nadie prometió que sobrevivirían a Cascade.

La alternativa es mantener esa capa completamente fuera del editor. MemoryLake es una capa de memoria de la que leen tus herramientas: las convenciones, decisiones y restricciones en un solo almacenamiento, accesible desde Claude Code a través de MCP y desde cualquier otra cosa a través de la API. La próxima vez que un editor cambie de marca, retire un agente o simplemente quieras probar algo nuevo, el conocimiento será una entrada de configuración en lugar de un ejercicio de reconstrucción.

Para ser justos con los archivos: CLAUDE.md tiene ventajas reales que un almacenamiento no tiene. Es texto plano, vive en el control de versiones, se revisa en las solicitudes de extracción (pull requests) y tu equipo lo hereda automáticamente. Consérvalo para las reglas permanentes; para eso sirve. La capa de memoria es para lo que se acumula: las peculiaridades de los proveedores, las razones detrás de las decisiones, las cosas que de otro modo solo descubrirías interrogando a un agente antes de desinstalarlo.

Paso 1: Crea una clave API

Genera una clave y realiza tu primera solicitud en unos 30 segundos. Mantenla en tu entorno o en un gestor de secretos en lugar de incluirla en línea en la configuración; ya estás volviendo a ingresar las credenciales de MCP para este movimiento, así que colócalas en un lugar donde no tengas que buscarlas la próxima vez.

Paso 2: Sube tus primeras memorias

Arrastra los documentos, imágenes y archivos que contienen lo que reconstruiste en el Paso 1, además del material de referencia al que apuntaban tus reglas: decisiones de arquitectura con sus razones, las peculiaridades de compilación, las restricciones. Sube fuentes en lugar de resúmenes siempre que puedas.

Paso 3: Conecta tu IA y agentes

Dale acceso a la memoria a Claude, Codex, OpenClaw y otros agentes de IA a través de MCP o la API. Claude Code admite servidores MCP, por lo que esta es una sola entrada de configuración, y el mismo almacenamiento se puede leer desde cualquier otra cosa que uses, que es el objetivo de hacerlo una sola vez.

La primera diferencia es que el ejercicio de interrogación del Paso 1 es el último. Lo que aprendiste sobre tu propio proyecto no se queda en un almacenamiento por máquina que no puedes exportar; está en un registro que puedes leer.

La segunda es la independencia de la máquina. Las memorias de Cascade eran locales, y también lo es la mayor parte de lo que las reemplazó: el propio conocimiento de Claude Code vive en archivos en un repositorio local. Un almacenamiento significa que una segunda computadora portátil, un contenedor o la sesión de un compañero de equipo comienzan desde el mismo conocimiento en lugar de desde cero.

La tercera aparece cuando ejecutas varias sesiones. Claude Code ahora puede hacer que las sesiones se envíen mensajes entre sí, lo cual es útil para la coordinación, pero un mensaje es texto que se pasa entre dos sesiones activas, no una base compartida. Un almacenamiento es lo que hace que la cuarta sesión de la próxima semana sepa lo que aprendió la primera.

Y hace que el próximo cambio de herramienta sea económico. El fin de la vida útil (EOL) de Cascade fue una fecha límite anunciada con anticipación, y aun así le costó a la gente su contexto acumulado. La versión de esta migración que no quieres repetir es aquella en la que el conocimiento está dentro de cualquier cosa a la que te cambies.

Interroga al antiguo agente antes de desinstalarlo

Este es el paso que todos se saltan y el único que es genuinamente irreversible. Las memorias autogeneradas son el resultado acumulado de cosas que dijiste una vez. Pregúntale al agente qué sabe sobre el proyecto, qué convenciones está siguiendo, qué evita, y escribe las respuestas antes de que la instalación desaparezca.

No confundas la alternativa con una migración

Que Devin Desktop lea .windsurf/rules/ como alternativa significa que tus reglas antiguas siguen funcionando, lo que hace que sea fácil creer que no hay nada que hacer. Si te vas a un editor diferente, esa alternativa es irrelevante: Claude Code no lee ninguna de esas rutas.

Trata el límite de 12,000 caracteres como una guía que debes mantener

El límite de reglas combinadas de Windsurf te obligaba a ser selectivo. CLAUDE.md no tiene tal restricción, y el resultado natural es un archivo que crece más allá del punto en el que el modelo presta atención a todo él. Elige un presupuesto de caracteres y apégate a él deliberadamente.

Audita tus scripts mientras estás en ello

El cambio de marca movió las rutas de las herramientas y los scripts no las siguieron. Cualquier cosa que haga referencia a una ruta de Windsurf ya está rota o a punto de estarlo. Solucionarlo durante una migración deliberada es mucho más económico que descubrirlo en la integración continua (CI).

Separa las reglas del conocimiento a medida que reconstruyes

CLAUDE.md es para reglas permanentes cortas que se cargan en cada tarea. Las razones, el historial y el material de referencia pertenecen a documentos o a un almacenamiento que se recupera cuando es relevante. Reconstruir todo como un único archivo de reglas largo recrea el problema del que te protegía el límite de caracteres.

Pasar de Windsurf a Claude Code implica dos tareas con costos muy diferentes. Mover las reglas es mecánico: recopilar .windsurfrules, .windsurf/rules/ y .devin/rules/, clasificarlas por alcance y colocarlas como ~/.claude/CLAUDE.md, un CLAUDE.md raíz confirmado en el control de versiones, y archivos de subdirectorio o documentos de referencia. Reemplazar las memorias de Cascade no es mecánico en absoluto: eran autogeneradas y locales, no hay exportación, y la única forma de recuperarlas es preguntarle al agente qué sabe antes de marcharte.

La lección que vale la pena aprender del fin de la vida útil de Cascade el 1 de julio es la que no tiene que ver con Windsurf: una capa de memoria que vive dentro de un producto tiene la vida útil de ese producto. Mantenerla en un almacenamiento del que leen tus editores es lo que hace que el próximo cambio de marca, retiro o cambio de opinión sea un cambio de configuración en lugar de una reconstrucción.