ある開発者が、数ヶ月前から使用していた Claude Code のワークフローを OpenCode に移行したところ、ファイル処理、ルール読み込み、ツール・インベントリ、スキル・メタデータ、そしてセッションをまたぐメモリ機能のすべてが崩壊していることに気づいた。彼が記録した修正方法は、Claude のエコシステムからオープンソースの代替手段へと移行しようとするすべての人にとって、実用的なチェックリストとなるだろう。

なぜ移行が重要だったのか

Claude Code のユーザーは、AI 駆動のコーディング・アシスタントを円滑に動作させるために、ルール、スキル定義、メモリログといった一連の密接に結合されたファイル群に依存している。著者のセットアップでは、ルールの読み込みが停止し、ファイルが混同され、トークン使用量が急増したため、日々のコーディング・ヘルパーとしての信頼性が失われてしまった。OpenCode は「パーミッション・ファースト（権限優先）」のセキュリティ、OpenRouter を介したモデルに依存しないアクセス、そして従量課金制を謳っており、非常に魅力的だ。しかし、移行は単純なコピー＆ペーストでは済まない。OpenCode が期待する形式で、すべてのコンポーネントを再定義する必要がある。

崩壊の原因

Claude Code は CLAUDE.md というファイルを使用していたが、OpenCode はこれを無視し、代わりに追加のメタデータとして AGENTS.md を読み込む。著者はこれら 2 つのシステムが互換性があると想定していたため、いくつかのコア要素が OpenCode から見えない状態になっていた。

具体的な失敗例とその修正方法

  • ルールファイルが無視される
    OpenCode は CLAUDE.md を決して読み込まない。解析するのは AGENTS.md のみだ。ファイル名を変更するだけでは不十分で、内容は新しい形式で再定義されなければならない。
    Fix: 新しい AGENTS.md を作成し、ルールのテキストをコピーして、新しい OpenCode セッションを開始し、エージェントに「私のルールは何ですか？」と尋ねる。もし引用できなければ、ルールは読み込まれていない。

  • ツール・インベントリの欠落
    スキルと MCP (multi-cloud platform) サーバーをコピーするはずだった移行コマンドは失敗した。なぜなら、OpenCode は一度も登録されていないツールをインベントリ（目録）化できないからだ。
    Fix: Claude Code のツールがまだ動作しているうちに、すべてのスキルとコマンドを手動でリストアップする。どれを OpenCode で再構築し、どれを破棄するかを決定する。

  • スキルからフロントマターが消失する
    移行されたスキルファイルは、モデルの割り当てやツールの取り扱い指示を含むフロントマターの大部分を失っていた。OpenCode が尊重するのはごく一部のフィールドのみであるため、インポートされたスキルは予測不能な挙動を示した。
    Fix: インポートされたスキルはすべて「壊れている」ものとして扱う。最も頻繁に使用する 3 つのスキルをゼロから再作成し、サポートされているフィールドのみが含まれていることを確認する。使用していないスキルファイルは削除する。

  • セッションをまたぐメモリがない
    Claude Code は、著者がコンテキストとして依存していた永続的な履歴を保持していた。OpenCode はセッションをまたいでメモリを維持しないため、アシスタントは切り替えの翌日にはすべてを「忘れて」しまった。
    Fix: AGENTS.md に明示的な指示を追加する：「各セッションの最後に、何を行ったか、何が保留中か、どのような決定がなされたかをカバーする短い要約を session-log.md に追記してください。」 これにより、セッションログが継続性のための「信頼できる唯一の情報源（single source of truth）」となる。

得られるものと失うもの

得られるもの

  • Permission-first security: OpenCode はアクションを実行する前に確認を求めるため、意図しないコード変更を減らすことができる。
  • Model freedom: 単一の API キーで OpenRouter を通じて数十のモデルを利用でき、設定ファイルを変更することなく実験が可能になる。
  • Cost control: 課金は使用量ベースであるため、トークン消費が急増した際に高額になりがちな定額制サブスクリプションを避けることができる。

失うもの

  • 組み込みの長期メモリがないため、手動のログを維持する必要がある。
  • スキルのメタデータが限られているため、カスタムツールのほとんどを再構築する必要がある。

実用的な移行チェックリスト

  1. まず AGENTS.md を作成する – 他のファイルをインポートする前に、必要なすべてのルールを宣言する。
  2. セッションログの指示を追加する – AGENTS.md の冒頭に「要約を追記する」ルールを組み込む。
  3. 上位 3 つのスキルを再構築する – サポートされているフィールドのみをコピーし、各スキルを単独でテストする。
  4. MCP を手動で再定義する – アクセスが必要な各サーバーまたはクラウドのエンドポイントをリストアップする。
  5. 検証する – 新しい OpenCode セッションを開始し、アシスタントに対してルール、スキルリスト、メモリの状態を問い合わせる。

まとめ

Claude Code から OpenCode への移行は、単なるファイルの移動ではなく、アシスタントを駆動する「宣言（declarations）」の再設計である。このプロセスにより、コアとなるルールへの絞り込み、不可欠なスキルの再構築、手動メモリログの採用を余儀なくされるが、同時に、より安価でモデルに依存しない AI アシスタンスへの道が開かれる。利便性よりもコントロールを重視する準備ができているなら、上記のチェックリストに従い、インポートされたすべてのコンポーネントを「新しい始まり」として扱ってほしい。