Un developer ha spostato un workflow di Claude Code risalente a mesi fa su OpenCode e ha scoperto che la gestione dei file, il caricamento delle regole, l'inventario degli strumenti, i metadati delle skill e la memoria tra le sessioni sono andati in pezzi. Le correzioni che ha documentato fungono ora da checklist pratica per chiunque passi dall'ecosistema di Claude all'alternativa open-source.

Perché la migrazione era importante

Gli utenti di Claude Code si affidano a un insieme strettamente integrato di file — regole, definizioni di skill e log di memoria — per mantenere un assistente di programmazione basato su IA fluido. Quando l'impostazione dell'autore ha smesso di caricare le regole, ha confuso i file e ha visto un picco nell'uso dei token, il suo aiuto quotidiano per la programmazione è diventato inaffidabile. OpenCode promette una "sicurezza basata sui permessi" (permission-first security), un accesso agnostico rispetto al modello tramite OpenRouter e un modello di prezzo pay-as-you-go, il che lo rende attraente. Ma la transizione non è un semplice copia-incolla; è necessario dichiarare nuovamente ogni componente nel formato previsto da OpenCode.

Cosa ha causato il malfunzionamento

Claude Code utilizzava un file chiamato CLAUDE.md, che OpenCode ignora, leggendo invece AGENTS.md per i metadati aggiuntivi. L'autore ha dato per scontato che i due sistemi fossero intercambiabili, lasciando diversi elementi fondamentali invisibili a OpenCode.

I fallimenti concreti e come risolverli

  • File delle regole ignorato
    OpenCode non legge mai CLAUDE.md; analizza solo AGENTS.md. Rinominare il file non basta perché il contenuto deve essere dichiarato nuovamente nel nuovo formato.
    Soluzione: Crea un nuovo AGENTS.md, copia il testo delle regole, avvia una nuova sessione OpenCode e chiedi all'agente "Quali sono le mie regole?". Se non riesce a citarle, le regole non sono state caricate.

  • Inventario degli strumenti mancante
    Il comando di migrazione che avrebbe dovuto copiare le skill e i server MCP (multi-cloud platform) è fallito perché OpenCode non può inventariare strumenti che non sono mai stati registrati.
    Soluzione: Mentre gli strumenti di Claude Code sono ancora attivi, elenca manualmente ogni skill e comando. Decidi quali ricostruire in OpenCode e quali abbandonare.

  • Front-matter rimosso dalle skill
    I file delle skill portati hanno perso la maggior parte del loro front-matter, inclusi gli assegnamenti dei modelli e le direttive per la gestione degli strumenti. OpenCode rispetta solo una manciata di campi, quindi le skill importate si comportavano in modo imprevedibile.
    Soluzione: Tratta ogni skill importata come se fosse guasta. Ricrea da zero le tre skill più utilizzate, assicurandoti che contengano solo i campi supportati. Elimina eventuali file di skill non utilizzati.

  • Nessuna memoria tra le sessioni
    Claude Code manteneva una cronologia persistente su cui l'autore faceva affidamento per il contesto. OpenCode non mantiene la memoria tra le sessioni, quindi l'assistente ha "dimenticato" tutto il giorno dopo il passaggio.
    Soluzione: Aggiungi un'istruzione esplicita in AGENTS.md: “Al termine di ogni sessione, aggiungi un breve riassunto a session-log.md che copra ciò che è stato fatto, ciò che è in sospeso e le decisioni prese.” Il log della sessione diventa così l'unica fonte di verità per la continuità.

La posta in gioco: cosa si guadagna e cosa si perde

Vantaggi

  • Sicurezza basata sui permessi: OpenCode chiede il permesso prima di eseguire qualsiasi azione, riducendo le modifiche accidentali al codice.
  • Libertà di modello: Una singola chiave API sblocca decine di modelli tramite OpenRouter, permettendoti di sperimentare senza cambiare i file di configurazione.
  • Controllo dei costi: La fatturazione è basata sull'utilizzo, evitando l'abbonamento a tariffa fissa che può diventare costoso quando il consumo di token aumenta improvvisamente.

Svantaggi

  • La mancanza di una memoria a lungo termine integrata significa che devi mantenere un log manuale.
  • I metadati limitati delle skill ti costringono a ricostruire la maggior parte dei tuoi strumenti personalizzati.

Una checklist pratica per la migrazione

  1. Crea prima AGENTS.md – dichiara ogni regola di cui hai bisogno prima di importare qualsiasi altro file.
  2. Aggiungi un'istruzione per il log della sessione – inserisci la regola "aggiungi riassunto" all'inizio di AGENTS.md.
  3. Ricostruisci le prime tre skill – copia solo i campi supportati; testa ogni skill singolarmente.
  4. Dichiara manualmente gli MCP – elenca ogni server o endpoint cloud che devi ancora raggiungere.
  5. Valida – avvia una nuova sessione OpenCode e interroga l'assistente sulle sue regole, sull'elenco delle skill e sullo stato della memoria.

In sintesi

Migrare da Claude Code a OpenCode non riguarda tanto lo spostamento di file, quanto la riprogettazione delle dichiarazioni che guidano l'assistente. Il processo ti costringe a ridurti alle regole fondamentali, ricostruire le skill essenziali e adottare un log di memoria manuale, ma apre anche la porta a un'assistenza AI più economica e agnostica rispetto al modello. Se sei pronto a scambiare la comodità con il controllo, segui la checklist sopra e tratta ogni componente importato come un nuovo inizio.