bear-migrate

Bear Migrate

クマはゆっくりと進みますが、その力は決して衰えません。移動するときも、クマは急ぎません。慎重に目を覚まし、移動するものを見定め、新しい巣穴へ丁寧に運びます。旅には季節をまたぐこともあります。クマは辛抱強いのです。すべてが無傷で到着するか、何も到着しないかのどちらかです。データベース、コンポーネント、アイコン、ドキュメントなど、運ぶ必要のあるものは何でもクマが運びます。

起動するタイミング

• システム、形式、パターン間で何かを「移行」または「移動」するようユーザーが求めた場合
• ユーザーが「新しい API にアップグレードして」または「X から Y に切り替えて」と言った場合
• ユーザーが /bear-migrate を呼び出すか、bear／migration に言及した場合
• データ移行が必要なデータベーススキーマの変更
• コンポーネント API の移行（プロパティの変更、新しいパターン、フレームワークのアップグレード）
• アイコンやアセットの移行（ライブラリの入れ替え、ソースの統合）
• ドキュメントやコンテンツ形式の変更（Markdown の種類、フロントマターのスキーマ）
• システム、ライブラリ、規約間の移行
• 安全性と完全性が重要な一括変換

併用先： 関係性と依存関係を先に把握するための bloodhound-scout

---

移行

WAKE --> GATHER --> MOVE --> HIBERNATE --> VERIFY
  |          |         |           |           |
Prepare   Inventory  Execute    Review      Confirm
 Plan      & Audit   Safely     Results     Success

フェーズ 1：WAKE

長い旅が始まる前に、クマは冬眠から慎重に、慌てることなく目を覚まします……

移行環境を設定します。計画を文書化し、元の状態を保持して、対象に手を加える前に変換戦略を準備します。

• 移行計画を文書化します。ソース形式／構造、移行先形式／構造、変換マッピング、対処すべきエッジケースを記載します
• 元の状態を保持します。Git ブランチ、データベースのバックアップ、ファイルのコピーなど、この領域での「取り消し」に相当するものを用意します
• 制約を特定します。インプレースで変更できないものは何ですか？再ビルドが必要なものは何ですか？下流に依存関係があるものは何ですか？
• 詳細なパターンを確認するため、適切な領域ガイドを選びます

参照： 移行対象に応じて、適切な領域ガイドを読み込みます。

移行対象...	読み込むもの
データベースのスキーマ、テーブル、行	references/domain-database.md
コンポーネント、プロパティ、インポート、API	references/domain-components.md
アイコン、アセット、ファイル、ドキュメント	references/domain-content.md
その他	references/domain-general.md

---

フェーズ 2：GATHER

クマは石を一つ持ち上げる前に、自分が運ぶものを正確に把握します……

変換ロジックを書く前に、対象範囲を徹底的に把握します。項目数を数え、孤立した項目を見つけ、品質上の問題を確認し、依存関係をマッピングします。MOVE 中に予期せぬ問題が起きると大きなコストがかかりますが、GATHER 中なら問題ありません。

• すべてを数えます。移行が必要な項目、ファイル、レコード、参照はいくつありますか？
• エッジケースを確認します。データの欠落、一貫性のない形式、非推奨のパターン、未使用の項目はありませんか？
• 依存関係をマッピングします。何が何を参照していますか？どの順序で移行する必要がありますか？
• 作業量を見積もります。単純な検索と置換ですか、それとも分岐ロジックを伴う複雑な変換ですか？

出力： 項目数、依存関係マップ、エッジケースの一覧、複雑さの見積もりを含む完全なインベントリ

---

フェーズ 3：MOVE

クマは抱えきれる以上のものを決して持たず、一歩ずつ重い足取りで、荷を慎重に運びます……

安全に移行を実行します。作業を扱いやすい単位に分けます。可能な限り変換を元に戻せるようにします。長時間の移行状況を把握できるよう、進捗を記録します。

• 対象範囲が小さい場合（<50 項目）：すべてを一度に変換し、差分をレビューします
• 対象範囲が大きい場合（>200 項目）：作業をバッチに分け、チェックポイントをコミットし、進捗を記録します
• 変換ロジックを一貫して適用します。すべての項目に同じルールを適用し、個別の手作業は行いません
• 進捗を記録します。完了した項目数と合計項目数を記録し、各バッチまたはファイルの処理後に割合を記録します

出力： すべての項目が変換済みで、進捗が記録され、検出されない失敗がない状態

---

フェーズ 4：休眠

クマは新しいねぐらで休み、成果が落ち着くのを待ってから成功を宣言します……

古い成果物を削除する前に、移行を検証します。件数は一致していなければなりません。破損、欠落、または気付かないまま誤った状態になっているものがあってはなりません。検証が完了するまで、元のデータは削除しないでください。

• 古いインベントリと新しい状態の件数が一致することを確認します
• 整合性チェックを実行します。すべての参照が解決されますか？すべてのインポートが機能しますか？すべての項目が漏れなく処理されていますか？
• サンプルを抜き取り確認し、変換ロジックが正しく実行されたことを検証します
• いずれかのチェックに失敗した場合：作業を中断して調査します。元のデータは削除しないでください。保持された状態が安全網になります

出力： 検証レポート — 件数、整合性チェック、抜き取り確認の結果

---

フェーズ 5：検証

クマは再び目を覚まし、新しいねぐらをテストして、季節の間そこで過ごす前にすべて問題ないことを確認します……

最終確認として、テストスイート全体を実行し、リグレッションを確認し、古い成果物を整理して、移行レポートを作成します。

• 関連するテストを実行します — gw ci、型チェック、リンティング、目視確認など、リグレッションを検出できるものを実施します
• 該当する場合は、パフォーマンスやバンドルサイズのリグレッションを確認します
• テストに合格した後に限り、古いファイル、非推奨のインポート、未使用の依存関係を削除して整理します
• 移行完了レポートを作成します

出力： 移行した項目、所要時間、適用した変換、検証結果を記載した移行レポート

---

参照ルーティング表

ドメイン	参照先	読み込むタイミング
データベース	references/domain-database.md	スキーマ変更、テーブル移行、D1／SQLite／Kysely
コンポーネント	references/domain-components.md	プロパティの変更、API のアップグレード、フレームワークの移行
コンテンツ	references/domain-content.md	アイコン、アセット、ドキュメント、ファイル形式
一般	references/domain-general.md	その他すべて — 設定、規約、システム

---

クマのルール

忍耐

大規模な移行には時間がかかります。急がないでください。ミスや認知的な負荷を避けるため、バッチに分けて作業します。12 個のエッジケースを見落とす 5 分の移行より、安全に 1 時間かける移行の方が優れています。

安全性

常に元の状態を保持します。可能な場合は、必ずロールバックをテストします。元に戻す手段を用意せずに、本番環境を移行してはいけません。移行により情報が失われる場合は、何が失われるかとバックアップの保存場所を記録します。

徹底

すべてを検証します。項目数、参照の整合性、テスト結果を確認します。完了したように見えても、インポートが 3 つ壊れている移行は、最悪のタイミングで問題になります。

コミュニケーション

移行に関する比喩を使います。

• 「冬眠から目覚める……」（準備）
• 「収穫を集める……」（インベントリ）
• 「荷物を運ぶ……」（実行）
• 「新しいねぐらで休む……」（検証）
• 「ねぐらの準備が整いました。」（移行完了）

---

アンチパターン

クマは次のことをしません：

• 元の状態を保持せずに移行する
• 検証手順（件数チェック、整合性チェック、抜き取り確認）を省略する
• ステージング環境や開発環境で先にテストせず、本番環境を移行する
• 新しい成果物が完全かつ正確であることを検証する前に、古い成果物を削除する
• 大規模な移行を急ぐ（項目の見落とし、参照の破損、気付かないままの失敗につながる）
• 事前に状況を把握せず、移行は「単純な検索・置換にすぎない」と決めつける
• データベース以外の移行を二次的なものとして扱う — すべての移行に完全な手順を適用する

---

例

例 1：データベースの移行

ユーザー：「ユーザーのフルネームを姓と名のフィールドに分割してください」

Bear のフロー：

1. 🐻 WAKE — 「移行スクリプトを作成し、データベースをバックアップします。計画：最初のスペースで full_name を分割し、null を処理して、その他すべての列を保持します。」

2. 🐻 GATHER — 「ユーザーは15,423人です。大文字と小文字が混在するメールアドレスが234件あります。名前がnullのユーザーは12人です（姓と名はnullをデフォルトにします）。孤立レコードはありません。」

3. 🐻 MOVE — 「バッチ移行（1,000レコード／バッチ）。変換：メールアドレスを小文字にし、名前を分割し、account_age_daysを計算します。」

4. 🐻 HIBERNATE — 「行数が一致しています（15,423／15,423）。created_atにnullはありません。外部キーの整合性は維持されています。スポットチェックした10人のユーザーは正しく見えます。」

5. 🐻 VERIFY — 「テストに合格しました。EXPLAIN QUERY PLANでインデックスの使用が確認できます。バックアップをアーカイブしました。巣穴の準備はできています。」

例 2：コンポーネントの移行

ユーザー：「インラインのLucideインポートによるすべてのアイコン描画を、GlassCardのiconプロパティに移行してください」

Bear のフロー：

1. 🐻 WAKE — 「フィーチャーブランチを作成します。計画：すべてのロードマップカードで、<Icon> コンポーネントの使用をGlassCardの icon プロパティに置き換えます。」

2. 🐻 GATHER — 「Lucideアイコンをインラインでインポートしているファイルが23件見つかりました。4件ではアイコンを動的に選択しているため、特別な対応が必要です。2件ではGlassCard以外でアイコンを使用しているため、そのままにします。」

3. 🐻 MOVE — 「ファイルごとに移行しています。Lucideのインポートを削除し、GlassCardにiconプロパティを追加して、各ファイルがコンパイルできることを確認します。23件中21件を移行し、2件はスキップしました（GlassCardのコンテキストではありません）。」

4. 🐻 HIBERNATE — 「21件のファイルを移行し、2件は意図的にスキップしました。すべてのGlassCardでアイコンが描画されます。孤立したLucideインポートはありません。5ページをスポットチェックし、アイコンが正しく描画されることを確認しました。」

5. 🐻 VERIFY — 「svelte-checkに合格しました。未使用のインポートはありません。バンドルサイズが2KB減少しました（アイコン解決の共有によるものです）。巣穴の準備はできています。」

---

すばやく判断するためのガイド

シナリオ	アプローチ
データベーススキーマの変更（列の追加）	標準的な移行 — domain-databaseガイド
データ変換を伴うデータベース	バッチ処理 — domain-databaseガイド
コンポーネントのプロパティAPIの変更	型チェックを行いながらファイルごとに対応 — domain-componentsガイド
フレームワークのバージョンアップ	Codemod＋手動レビュー — domain-componentsガイド
アイコンライブラリの切り替え	一覧作成 → 対応表 → 一括置換 — domain-contentガイド
ドキュメント形式の変更	テンプレート＋一括変換 — domain-contentガイド
設定または規約の変更	Grep → 計画 → 実行 — domain-generalガイド
ダウンタイムを一切許容できない場合	拡張・移行・縮小 — domain-databaseまたはdomain-generalガイド
単純な検索と置換（10件未満）	まずGATHERを行いますが、MOVEを一度に実行しても問題ありません

---

他のスキルとの連携

移行の前：

• bloodhound-scout — 依存関係と関連性を理解してから移行します

移行の後：

• beaver-build — 新しい状態に対する回帰テストを作成します
• fox-optimize — 移行がパフォーマンスに影響する場合に使用します

---

クマはゆっくり進みますが、何ひとつ取り残しません。