Un développeur a migré un flux de travail Claude Code vieux de plusieurs mois vers OpenCode et a découvert que la gestion des fichiers, le chargement des règles, l'inventaire des outils, les métadonnées des compétences et la mémoire inter-sessions s'étaient tous effondrés. Les correctifs qu'il a documentés servent désormais de checklist pratique pour toute personne passant de l'écosystème de Claude à l'alternative open-source.

Pourquoi la migration était importante

Les utilisateurs de Claude Code dépendent d'un ensemble de fichiers étroitement liés — règles, définitions de compétences et journaux de mémoire — pour assurer le bon fonctionnement d'un assistant de codage piloté par l'IA. Lorsque la configuration de l'auteur a cessé de charger les règles, a mélangé les fichiers et a vu l'utilisation des tokens grimper, son assistant de codage quotidien est devenu peu fiable. OpenCode promet une « sécurité axée sur les permissions », un accès agnostique au modèle via OpenRouter et une tarification à l'usage, ce qui le rend attractif. Mais la transition n'est pas un simple copier-coller ; vous devez redéclarer chaque composant au format attendu par OpenCode.

Ce qui a causé la rupture

Claude Code utilisait un fichier nommé CLAUDE.md, qu'OpenCode ignore au profit de AGENTS.md pour les métadonnées supplémentaires. L'auteur a supposé que les deux systèmes étaient interchangeables, laissant plusieurs éléments essentiels invisibles pour OpenCode.

Les échecs concrets et comment les corriger

  • Fichier de règles ignoré
    OpenCode ne lit jamais CLAUDE.md ; il analyse uniquement AGENTS.md. Renommer le fichier ne suffit pas car le contenu doit être redéclaré dans le nouveau format.
    Correction : Créez un nouveau fichier AGENTS.md, copiez le texte des règles, lancez une nouvelle session OpenCode et demandez à l'agent : « Quelles sont mes règles ? ». S'il ne peut pas les citer, c'est que les règles n'ont pas été chargées.

  • Inventaire des outils manquant
    La commande de migration censée copier les compétences et les serveurs MCP (multi-cloud platform) a échoué car OpenCode ne peut pas inventorier des outils qui n'ont jamais été enregistrés.
    Correction : Tant que les outils de Claude Code sont encore opérationnels, listez manuellement chaque compétence et commande. Décidez de celles que vous allez reconstruire dans OpenCode et de celles que vous allez abandonner.

  • Front-matter supprimé des compétences
    Les fichiers de compétences portés ont perdu la majeure partie de leur front-matter, y compris les affectations de modèles et les directives de gestion des outils. OpenCode ne respecte qu'un petit nombre de champs, de sorte que les compétences importées se comportaient de manière imprévisible.
    Correction : Considérez chaque compétence importée comme défectueuse. Recréez de zéro les trois compétences les plus utilisées, en veillant à ce qu'elles ne contiennent que les champs pris en charge. Supprimez tout fichier de compétence inutilisé.

  • Absence de mémoire inter-sessions
    Claude Code conservait un historique persistant sur lequel l'auteur s'appuyait pour le contexte. OpenCode ne maintient pas de mémoire entre les sessions, l'assistant a donc « tout oublié » dès le lendemain du changement.
    Correction : Ajoutez une instruction explicite dans AGENTS.md : « À la fin de chaque session, ajoutez un court résumé à session-log.md couvrant ce qui a été fait, ce qui est en attente et les décisions prises. » Le journal de session devient alors la source unique de vérité pour la continuité.

Les enjeux : ce que vous gagnez et ce que vous perdez

Gains

  • Sécurité axée sur les permissions : OpenCode demande l'autorisation avant d'exécuter toute action, réduisant ainsi les modifications de code accidentelles.
  • Liberté de modèle : Une seule clé API débloque des dizaines de modèles via OpenRouter, vous permettant d'expérimenter sans modifier les fichiers de configuration.
  • Contrôle des coûts : La facturation est basée sur l'utilisation, évitant l'abonnement à forfait qui peut devenir coûteux lorsque la consommation de tokens grimpe en flèche.

Pertes

  • L'absence de mémoire à long terme intégrée signifie que vous devez tenir un journal manuel.
  • Les métadonnées de compétences limitées vous obligent à reconstruire la plupart de vos outils personnalisés.

Une checklist de migration pratique

  1. Créez d'abord AGENTS.md – déclarez chaque règle nécessaire avant d'importer d'autres fichiers.
  2. Ajoutez une instruction de journal de session – intégrez la règle « ajouter un résumé » en haut de AGENTS.md.
  3. Reconstruisez les trois compétences principales – ne copiez que les champs pris en charge ; testez chaque compétence de manière isolée.
  4. Redéclarez manuellement les MCP – listez chaque serveur ou point de terminaison cloud que vous devez toujours atteindre.
  5. Validez – lancez une nouvelle session OpenCode et interrogez l'assistant sur ses règles, sa liste de compétences et son état de mémoire.

À retenir

Migrer de Claude Code vers OpenCode consiste moins à déplacer des fichiers qu'à réarchitecturer les déclarations qui pilotent l'assistant. Le processus vous oblige à revenir à l'essentiel (règles de base), à reconstruire les compétences indispensables et à adopter un journal de mémoire manuel, mais il ouvre également la porte à une assistance IA moins chère et agnostique vis-à-vis des modèles. Si vous êtes prêt à échanger la commodité contre le contrôle, suivez la checklist ci-dessus et traitez chaque composant importé comme un nouveau départ.