Deweloper przeniósł wielomiesięczny workflow Claude Code do OpenCode i odkrył, że obsługa plików, ładowanie reguł, inwentaryzacja narzędzi, metadane umiejętności oraz pamięć między sesjami przestały działać. Dokumentacja poprawek służy teraz jako praktyczna lista kontrolna dla każdego, kto przechodzi z ekosystemu Claude do alternatywy open-source.

Dlaczego ta migracja była ważna

Użytkownicy Claude Code polegają na ściśle powiązanym zestawie plików – regułach, definicjach umiejętności i logach pamięci – aby zapewnić płynne działanie asystenta kodowania opartego na AI. Gdy konfiguracja autora przestała ładować reguły, pomieszała pliki i spowodowała gwałtowny wzrost zużycia tokenów, jego codzienny pomocnik w kodowaniu stał się niepewny. OpenCode obiecuje „bezpieczeństwo oparte na uprawnieniach” (permission-first security), dostęp niezależny od modelu poprzez OpenRouter oraz model płatności pay-as-you-go, co czyni go atrakcyjnym. Jednak przejście nie polega na prostym kopiowaniu i wklejaniu; należy ponownie zadeklarować każdy komponent w formacie oczekiwanym przez OpenCode.

Co doprowadziło do awarii

Claude Code używał pliku o nazwie CLAUDE.md, który OpenCode ignoruje, czytając zamiast tego AGENTS.md w celu uzyskania dodatkowych metadanych. Autor założył, że oba systemy są zamienne, przez co kilka kluczowych elementów stało się niewidocznych dla OpenCode.

Konkretne błędy i sposoby ich naprawy

  • Ignorowanie pliku reguł
    OpenCode nigdy nie czyta CLAUDE.md; analizuje jedynie AGENTS.md. Sama zmiana nazwy pliku nie wystarczy, ponieważ treść musi zostać ponownie zadeklarowana w nowym formacie.
    Fix: Utwórz nowy plik AGENTS.md, skopiuj tekst reguł, uruchom nową sesję OpenCode i zapytaj agenta: „Jakie są moje reguły?”. Jeśli nie potrafi ich przytoczyć, oznacza to, że reguły nie zostały załadowane.

  • Brak inwentaryzacji narzędzi
    Komenda migracyjna, która miała skopiować umiejętności i serwery MCP (multi-cloud platform), zawiodła, ponieważ OpenCode nie może zinwentaryzować narzędzi, które nigdy nie zostały zarejestrowane.
    Fix: Dopóki narzędzia Claude Code wciąż działają, wypisz ręcznie każdą umiejętność i komendę. Zdecyduj, które z nich należy odbudować w OpenCode, a które porzucić.

  • Usunięcie front-matter ze umiejętności
    Przeniesione pliki umiejętności straciły większość swojego front-matteru, w tym przypisania modeli i dyrektywy obsługi narzędzi. OpenCode respektuje tylko kilka pól, przez co zaimportowane umiejętności zachowywały się nieprzewidywalnie.
    Fix: Traktuj każdą zaimportowaną umiejętność jako uszkodzoną. Odbuduj od zera trzy najczęściej używane umiejętności, upewniając się, że zawierają tylko obsługiwane pola. Usuń wszystkie nieużywane pliki umiejętności.

  • Brak pamięci między sesjami
    Claude Code utrzymywał trwałą historię, na której autor polegał w celu zachowania kontekstu. OpenCode nie utrzymuje pamięci między sesjami, więc asystent „zapomniał” wszystkiego dzień po przejściu na nowy system.
    Fix: Dodaj wyraźną instrukcję do AGENTS.md: „Na koniec każdej sesji dopisz krótki podsumowanie do pliku session-log.md, obejmujące to, co zostało zrobione, co jest w toku oraz podjęte decyzje.” Log sesji staje się wtedy jedynym źródłem prawdy zapewniającym ciągłość.

Stawka: co zyskujesz, a co tracisz

Zyski

  • Permission-first security: OpenCode pyta o zgodę przed wykonaniem jakiejkolwiek akcji, co zmniejsza ryzyko przypadkowych zmian w kodzie.
  • Model freedom: Pojedynczy klucz API odblokowuje dziesiątki modeli poprzez OpenRouter, co pozwala na eksperymentowanie bez zmiany plików konfiguracyjnych.
  • Cost control: Rozliczenia są oparte na zużyciu, co pozwala uniknąć stałego abonamentu, który może stać się kosztowny przy nagłym wzroście zużycia tokenów.

Straty

  • Brak wbudowanej długoterminowej pamięci oznacza konieczność prowadzenia ręcznego logu.
  • Ograniczone metadane umiejętności zmuszają do odbudowania większości własnych narzędzi.

Praktyczna lista kontrolna migracji

  1. Najpierw utwórz AGENTS.md – zadeklaruj każdą potrzebną regułę przed importowaniem jakichkolwiek innych plików.
  2. Dodaj instrukcję logowania sesji – umieść regułę „dopisuj podsumowanie” na górze AGENTS.md.
  3. Odbuduj trzy najważniejsze umiejętności – skopiuj tylko obsługiwane pola; przetestuj każdą umiejętność w izolacji.
  4. Ręcznie zadeklaruj MCP – wypisz każdy serwer lub punkt końcowy chmury, do którego nadal musisz mieć dostęp.
  5. Zweryfikuj – uruchom nową sesję OpenCode i zapytaj asystenta o jego reguły, listę umiejętności i status pamięci.

Podsumowanie

Migracja z Claude Code do OpenCode to w mniejszym stopniu przenoszenie plików, a w większym rearchitekturyzacja deklaracji sterujących asystentem. Proces ten zmusza do ograniczenia się do podstawowych reguł, odbudowania niezbędnych umiejętności i przyjęcia ręcznego logu pamięci, ale otwiera również drzwi do tańszej, niezależnej od modelu pomocy AI. Jeśli jesteś gotowy wymienić wygodę na kontrolę, postępuj zgodnie z powyższą listą kontrolną i traktuj każdy zaimportowany komponent jako nowy początek.