Un desarrollador trasladó un flujo de trabajo de Claude Code de hace meses a OpenCode y descubrió que el manejo de archivos, la carga de reglas, el inventario de herramientas, los metadatos de habilidades y la memoria entre sesiones fallaron por completo. Las correcciones que documentó sirven ahora como una lista de verificación práctica para cualquiera que esté pasando del ecosistema de Claude a la alternativa de código abierto.

Por qué la migración era importante

Los usuarios de Claude Code dependen de un conjunto de archivos estrechamente vinculados —reglas, definiciones de habilidades y registros de memoria— para mantener un asistente de codificación impulsado por IA funcionando sin problemas. Cuando la configuración del autor dejó de cargar reglas, mezcló archivos y vio un aumento en el uso de tokens, su ayudante de codificación diario se volvió poco confiable. OpenCode promete "seguridad basada en permisos" (permission-first security), acceso agnóstico al modelo a través de OpenRouter y precios de pago por uso, lo que lo hace atractivo. Pero la transición no es un simple copiar y pegar; debes volver a declarar cada componente en el formato que OpenCode espera.

Qué provocó el fallo

Claude Code utilizaba un archivo llamado CLAUDE.md, el cual OpenCode ignora y, en su lugar, lee AGENTS.md para obtener metadatos adicionales. El autor asumió que ambos sistemas eran intercambiables, dejando varias piezas fundamentales invisibles para OpenCode.

Los fallos concretos y cómo solucionarlos

  • El archivo de reglas es ignorado
    OpenCode nunca lee CLAUDE.md; solo analiza AGENTS.md. Renombrar el archivo no es suficiente porque el contenido debe declararse de nuevo en el nuevo formato.
    Solución: Crea un nuevo AGENTS.md, copia el texto de las reglas, inicia una nueva sesión de OpenCode y pregunta al agente: "¿Cuáles son mis reglas?". Si no puede citarlas, es que las reglas no se han cargado.

  • Falta el inventario de herramientas
    El comando de migración que debía copiar las habilidades y los servidores MCP (multi-cloud platform) falló porque OpenCode no puede inventariar herramientas que nunca fueron registradas.
    Solución: Mientras las herramientas de Claude Code sigan funcionando, enumera manualmente cada habilidad y comando. Decide cuáles reconstruir en OpenCode y cuáles descartar.

  • Pérdida del front-matter en las habilidades
    Los archivos de habilidades portados perdieron la mayor parte de su front-matter, incluyendo las asignaciones de modelos y las directivas de manejo de herramientas. OpenCode solo respeta un puñado de campos, por lo que las habilidades importadas se comportaron de manera impredecible.
    Solución: Trata cada habilidad importada como si estuviera rota. Recrea las tres habilidades más utilizadas desde cero, asegurándote de que contengan solo los campos compatibles. Elimina cualquier archivo de habilidad que no se utilice.

  • Sin memoria entre sesiones
    Claude Code mantenía un historial persistente en el que el autor confiaba para el contexto. OpenCode no mantiene la memoria entre sesiones, por lo que el asistente "olvidó" todo al día siguiente del cambio.
    Solución: Añade una instrucción explícita a AGENTS.md: “Al final de cada sesión, añade un breve resumen a session-log.md que cubra lo que se hizo, lo que está pendiente y las decisiones tomadas”. El registro de sesión se convierte entonces en la única fuente de verdad para la continuidad.

Lo que está en juego: qué ganas y qué pierdes

Ganancias

  • Seguridad basada en permisos: OpenCode pregunta antes de ejecutar cualquier acción, reduciendo los cambios accidentales en el código.
  • Libertad de modelo: Una única clave de API desbloquea docenas de modelos a través de OpenRouter, permitiéndote experimentar sin cambiar los archivos de configuración.
  • Control de costes: La facturación se basa en el uso, evitando la suscripción de tarifa plana que puede volverse costosa cuando el consumo de tokens aumenta.

Pérdidas

  • La falta de memoria a largo plazo integrada significa que debes mantener un registro manual.
  • Los metadatos de habilidades limitados te obligan a reconstruir la mayoría de tus herramientas personalizadas.

Una lista de verificación práctica para la migración

  1. Crea primero AGENTS.md – declara cada regla que necesites antes de importar cualquier otro archivo.
  2. Añade una instrucción de registro de sesión – incluye la regla de "añadir resumen" en la parte superior de AGENTS.md.
  3. Reconstruye las tres habilidades principales – copia solo los campos compatibles; prueba cada habilidad de forma aislada.
  4. Redeclara manualmente los MCP – enumera cada servidor o endpoint de la nube al que aún necesites acceder.
  5. Valida – inicia una nueva sesión de OpenCode y consulta al asistente sobre sus reglas, su lista de habilidades y su estado de memoria.

Conclusión

Migrar de Claude Code a OpenCode trata menos de mover archivos y más de reestructurar las declaraciones que impulsan al asistente. El proceso te obliga a reducirte a las reglas básicas, reconstruir habilidades esenciales y adoptar un registro de memoria manual, pero también abre la puerta a una asistencia de IA más económica y agnóstica al modelo. Si estás listo para cambiar la comodidad por el control, sigue la lista de verificación anterior y trata cada componente importado como un nuevo comienzo.