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

Primero, a qué versión de OpenCode te vas a mudar

La guía de migración de OpenCode señala que "tanto OpenCode 1 como OpenCode 2 utilizan el comando opencode y ya no se instalan uno al lado del otro de forma predeterminada". Las dos versiones leen las mismas ubicaciones de configuración, y la guía dice que el comportamiento compatible de V1 "está destinado a seguir siendo compatible con V1". Pero en los archivos específicos de Claude Code difieren, así que verifica cuál estás ejecutando antes de confiar en lo que se detalla a continuación.

Instrucciones: CLAUDE.md

En V1, CLAUDE.md funciona como una alternativa. OpenCode lee un archivo CLAUDE.md del proyecto si no existe ningún AGENTS.md, y ~/.claude/CLAUDE.md si no hay un AGENTS.md global de OpenCode. La regla es "El primer archivo que coincida gana en cada categoría". Por lo tanto, agregar un AGENTS.md a un proyecto desactiva su CLAUDE.md.

V1 también te ofrece interruptores para esta compatibilidad. "Para deshabilitar la compatibilidad con Claude Code, establece una de estas variables de entorno". OPENCODE_DISABLE_CLAUDE_CODE desactiva todo el soporte de .claude, mientras que OPENCODE_DISABLE_CLAUDE_CODE_PROMPT y OPENCODE_DISABLE_CLAUDE_CODE_SKILLS desactivan el CLAUDE.md global y las habilidades por separado.

En V2, no hay alternativa. V2 carga un AGENTS.md global y luego "cada AGENTS.md desde el directorio del espacio de trabajo actual hacia el directorio de inicio", y los archivos más profundos en el proyecto se cargan a medida que el agente lee esa área. También los acumula en lugar de elegir uno: "OpenCode combina los archivos y no resuelve conflictos entre ellos".

La guía de migración de V2 se dirige directamente a los usuarios de Claude Code: "Si una configuración de V1 dependía de una alternativa de CLAUDE.md, mueve esa guía al AGENTS.md correspondiente". Agrega que "V2 actualmente solo descubre AGENTS.md" y, dado que el comportamiento de V1 está destinado a seguir siendo compatible, pide a los usuarios que "también presenten un problema de compatibilidad con los detalles del proyecto afectado". La palabra actualmente importa. Esto podría cambiar, pero hoy en día V2 no carga un CLAUDE.md por sí solo.

El movimiento seguro para cualquiera de las dos versiones es el mismo: coloca tus instrucciones en AGENTS.md. Claude Code también puede leerlo, como explica nuestra guía sobre el valor predeterminado de AGENTS.md en Claude Code, por lo que un solo archivo puede servir para ambas herramientas.

Importaciones y reglas con alcance de ruta

El archivo CLAUDE.md de Claude Code puede incorporar otros archivos. "Los archivos importados se expanden y se cargan en el contexto al inicio junto con el CLAUDE.md que los referencia". Si tu CLAUDE.md es principalmente una lista de líneas @docs/..., la mayoría de tus instrucciones residen en esos otros archivos.

La documentación de reglas de V1 de OpenCode dice: "Aunque opencode no analiza automáticamente las referencias de archivos en AGENTS.md, puedes lograr una funcionalidad similar de dos maneras". Su ruta recomendada es el campo instructions en opencode.json. V2 lo mantiene: "Utiliza la matriz de instrucciones para agregar archivos, patrones glob o URL HTTP(S) junto con los archivos AGENTS.md descubiertos". Si incluyes URL remotas allí, nuestra guía para reflejar los archivos de instrucciones remotas de OpenCode cubre lo que sucede cuando una descarga es lenta.

Claude Code también admite reglas en .claude/rules/, con un frontmatter paths: que limita una regla a los archivos coincidentes. La documentación de instrucciones de OpenCode describe los archivos AGENTS.md y la matriz instructions, y .claude/rules/ no se encuentra entre las ubicaciones que enumera. El patrón de OpenCode más cercano es un AGENTS.md anidado en el directorio que cubre la regla. En V2, los archivos anidados se "cargan primero los más cercanos" a medida que el agente lee esa parte del proyecto.

Habilidades (Skills)

Las habilidades son la parte que se traslada más fácilmente. Ambas versiones leen las carpetas de habilidades de Claude Code. V2 enumera ~/.claude/skills como una fuente de compatibilidad global y .claude/skills como una fuente de compatibilidad de proyecto, junto con el propio .opencode/skills de OpenCode.

V2 también entiende un campo de Claude Code. Su tabla enumera disable-model-invocation con la nota "Establecer en true para obtener el mismo efecto que opencode/autoinvoke: false". Se aceptan campos del estándar de habilidades abiertas, aunque "V2 acepta campos de portabilidad como licencia y compatibilidad, pero no los interpreta".

Los campos que enumera la documentación de habilidades de V2 son name, description, metadata.opencode/autoinvoke y disable-model-invocation. Los otros campos de habilidades de Claude Code, como context, paths, hooks y model, no se encuentran entre ellos, por lo que las habilidades que dependen de ellos necesitan una reescritura. Una diferencia más a tener en cuenta: en V2, "La ruta del archivo determina el ID de la habilidad. El nombre del frontmatter es solo una etiqueta de visualización".

Subagentes y comandos

Los subagentes de Claude Code residen en ~/.claude/agents/ o en el .claude/agents/ de un proyecto. Los archivos de agentes de OpenCode residen en ~/.config/opencode/agents/<name>.md o .opencode/agents/<name>.md, y su frontmatter es el propio de OpenCode, con una configuración mode: subagent y una lista de permisos. El cuerpo de Markdown se transfiere limpiamente, ya que en OpenCode "El cuerpo de Markdown se convierte en el prompt del sistema del agente".

Los comandos personalizados siguen el mismo patrón. Los archivos .claude/commands/ de Claude Code se convierten en .opencode/commands/<name>.md, o ~/.config/opencode/commands/ para los globales. Los comandos de OpenCode también utilizan $ARGUMENTS, y ten en cuenta que "Solo se descubren archivos .md".

Si utilizas mucho los subagentes, nuestra guía sobre por qué los subagentes de Claude Code no comparten memoria cubre lo que ve cada uno, lo cual vale la pena volver a verificar después de una migración.

Qué se queda atrás

Memoria automática (Auto memory). Claude Code escribe sus propias notas: "La memoria automática permite a Claude acumular conocimiento a través de las sesiones sin que tengas que escribir nada". Se almacenan en tu máquina, y "Cada proyecto tiene su propio directorio de memoria en ~/.claude/projects/<project>/memory/". La documentación de OpenCode no describe la lectura de ese directorio. Lo que sea que Claude haya aprendido allí, como tus correcciones, preferencias y datos del proyecto, se queda con Claude Code a menos que lo muevas a mano. Nuestra guía para migrar de Claude Code a Cursor cubre la misma brecha para otro destino.

Sesiones. La CLI de V1 de OpenCode puede exportar e importar datos de sesión como JSON, pero esos comandos describen las propias sesiones de OpenCode. Tus conversaciones de Claude Code se quedan en Claude Code. Nuestra guía para exportar una sesión de Claude Code a otra máquina cubre cómo conservarlas.

Hooks y plugins. Los hooks de Claude Code residen en su configuración. En su lugar, OpenCode extiende el comportamiento a través de plugins, y la guía de V2 advierte que "las implementaciones de plugins de V1 no se ejecutan en V2". Trata los hooks como algo que debes reconstruir, no copiar.

Servidores MCP. Estos se mueven como configuración. OpenCode los define en opencode.json, y V2 los agrupa bajo una clave servers. Vuelve a conectar cada uno e inicia sesión nuevamente donde sea necesario.

Paso 1: Crea un único AGENTS.md que OpenCode leerá, en cualquiera de las dos versiones

Comienza recopilando todo lo que define cómo funciona Claude en este proyecto:

• Tus archivos CLAUDE.md, en la raíz del proyecto, en .claude/CLAUDE.md, en subdirectorios y en ~/.claude/CLAUDE.md.
• Cada archivo que importan con @.
• Tus archivos .claude/rules/, tomando nota de cuáles usan paths:.
• Tu memoria automática. Abre ~/.claude/projects/<project>/memory/ y lee MEMORY.md y los archivos de temas a los que apunta.

Luego escribe el resultado en AGENTS.md:

• Las instrucciones para todo el proyecto van en el AGENTS.md raíz. Copia el contenido de los archivos importados o lístalos en la matriz instructions en opencode.json para que se carguen sin tener que pegarlos.
• Las reglas con alcance de ruta van en un AGENTS.md en el directorio que cubren.
• Las notas de memoria automática se clasifican. Las correcciones y los datos del proyecto que aún vigentes se convierten en instrucciones. Las preferencias personales que se aplican a varios proyectos van en ~/.config/opencode/AGENTS.md. Cualquier cosa desactualizada se queda atrás.
• Las instrucciones globales de ~/.claude/CLAUDE.md se mueven a ~/.config/opencode/AGENTS.md.

Si vas a seguir usando Claude Code en el mismo repositorio, mantén CLAUDE.md como un archivo corto que apunte a Claude hacia AGENTS.md, para que ambas herramientas lean un único conjunto de instrucciones. Nuestra guía para migrar CLAUDE.md a AGENTS.md cubre ese patrón.

Debido a que V2 combina cada AGENTS.md que encuentra sin resolver conflictos, lee los archivos juntos una vez que hayas terminado y elimina las contradicciones.

Paso 2: Mueve habilidades, agentes y comandos, luego realiza pruebas sin las alternativas

Las habilidades pueden quedarse donde están, ya que OpenCode lee .claude/skills/ y ~/.claude/skills/. Abre cada SKILL.md y verifica su frontmatter. Conserva name, description y disable-model-invocation. Reescribe cualquier cosa que dependa de campos exclusivos de Claude Code y mantén estable el nombre de cada carpeta, ya que en V2 la ruta establece el ID de la habilidad.

Los subagentes se mueven de .claude/agents/ a .opencode/agents/. Conserva el cuerpo de Markdown, establece mode: subagent y traduce las restricciones de herramientas en permisos de OpenCode.

Los comandos se mueven de .claude/commands/ a .opencode/commands/. Verifica que el uso de $ARGUMENTS de cada plantilla siga teniendo sentido.

Luego realiza la prueba. En V1, establece OPENCODE_DISABLE_CLAUDE_CODE en tu entorno para una sesión y confirma que el agente sigue tus instrucciones. Esa variable también desactiva .claude/skills, por lo que las habilidades que dejaste allí desaparecerán durante esa sesión. Cualquier instrucción que falte provenía de un archivo de Claude Code que aún no has movido. En V2, no es necesaria tal prueba, porque la alternativa no está allí. Inicia una sesión, pídele al agente que resuma las instrucciones bajo las que está trabajando y compáralas con tu AGENTS.md. Un detalle de V2 para las pruebas: "Las ediciones en un archivo anidado no se detectan automáticamente después de que se carga". Inicia una nueva sesión después de cambiar uno.

El paso 1 es la parte difícil de esta migración, y gran parte del trabajo está en las notas de memoria automática y los archivos importados, el contexto que Claude Code acumuló sin que fuera un solo archivo obvio. Moverlo a AGENTS.md soluciona esta migración. Pero no ayuda para la siguiente, y no cubre el contexto que te pertenece a ti en lugar de al repositorio.

MemoryLake es una capa de memoria para mantener decisiones y preferencias en una sola lista que tú mantienes, disponible para Claude Code y los demás asistentes que conectes.

Tú mismo escribes las entradas, con tus propias palabras. No se lee, escribe ni elimina nada de tus archivos CLAUDE.md, de la memoria automática de Claude Code, de tu configuración de OpenCode ni del almacenamiento de ningún proveedor. Verifica la política de tu organización antes de almacenar detalles del proyecto fuera de tu repositorio.

Paso 1: Crea una clave API

Inicia sesión y genera una clave desde el panel de control. La clave pertenece a tu espacio de trabajo de MemoryLake y es independiente de tu cuenta de Anthropic y de tus proveedores de modelos.

Paso 2: Sube tus primeras memorias

Comienza con lo que encontraste en la memoria automática que no sea una regla del repositorio: tus preferencias, el razonamiento detrás de las decisiones, los enfoques que descartaste. Una decisión por entrada, con fecha.

Paso 3: Conecta tu IA y agentes

Conecta los asistentes que utilizas. El contexto estará disponible dondequiera que trabajes, en lugar de estar atado a la herramienta que lo aprendió primero.

La primera diferencia es un único archivo de instrucciones en lugar de una cadena de alternativas. Con AGENTS.md en su lugar, OpenCode lee tus instrucciones en V1 y V2, y Claude Code puede leer el mismo archivo.

La segunda es que nada importante reside únicamente en la memoria automática de Claude. Leerla durante la migración convierte las notas que Claude escribió para sí mismo en instrucciones que puedes ver y editar.

La tercera es una prueba que puedes repetir. Desactivar la compatibilidad con V1, o ejecutar V2, muestra exactamente lo que lee OpenCode, para que sepas que la migración se ha completado en lugar de simplemente esperarlo.

Verifica primero tu versión de OpenCode. V1 lee CLAUDE.md como alternativa. V2 no lo hace.

Escribe AGENTS.md, no CLAUDE.md. Funciona en ambas versiones y en Claude Code.

Resuelve las importaciones. Pega el contenido importado o utiliza la matriz instructions.

Lee tu memoria automática antes de irte. Es la única fuente que escribió Claude en lugar de ti.

Deja las habilidades en .claude/skills/ si lo deseas. OpenCode las lee, pero verifica el frontmatter.

Mueve los agentes y comandos a .opencode/. Sus carpetas de Claude Code no están en las listas de OpenCode.

Realiza pruebas con las alternativas desactivadas. Esto muestra qué sigue dependiendo de los archivos de Claude Code.

La documentación de OpenCode se ha dirigido a los usuarios de Claude Code desde el principio, y para las habilidades la migración sigue siendo fácil: ambas versiones leen .claude/skills. Para las instrucciones, el panorama depende de la versión. V1 lee CLAUDE.md cuando no hay AGENTS.md. V2 reconoce únicamente AGENTS.md, y su guía de migración te indica que traslades la guía allí.

El camino confiable es el mismo en cualquier caso. Crea un AGENTS.md a partir de tus archivos CLAUDE.md, sus importaciones, tus reglas con alcance de ruta y la memoria automática que Claude guardó para sí mismo. Mueve los subagentes y comandos a .opencode/, verifica el frontmatter de las habilidades y realiza pruebas con las alternativas desactivadas. Así, OpenCode funcionará a partir de tu contexto, independientemente de la versión que ejecutes.