sanity-migration

Sanity 移行

このスキルは、CMS から Sanity への移行作業に使用します。移行は、単純なリフト＆シフトではなく、コンテンツ戦略と ETL のプロジェクトとして扱ってください。

必須のワークフロー

1. 最初に references/general.md を読みます。
2. 移行元のプラットフォームがわかっている場合は、該当するガイドも読みます。
   • AEM / Adobe Experience Manager：references/aem.md
   • Contentful：references/contentful.md
   • Strapi：references/strapi.md
   • Webflow：references/webflow.md
   • WordPress / WXR / Elementor：references/wordpress.md
   • Payload：references/payload.md
   • Drupal：references/drupal.md
   • Markdown / MDX / frontmatter ファイル：references/markdown.md
3. コードを書く前に、移行元へのアクセス、コンテンツの対象範囲、スキーマの決定、抽出、変換、インポート、検証、リダイレクト、切り替えを網羅した簡潔な移行計画を作成します。
4. 実際の移行では、決定的で再実行可能なスクリプトを優先します。移行スクリプト、マッピング、検証チェックを作成してレビューし、大量のコンテンツに対して一度きりのコンテンツ操作に頼らないでください。

作成する成果物

実装または計画のタスクでは、次の成果物を作成するか、不要な理由を説明してください。

• コンテンツインベントリ：移行元の種類、件数、ロケール、公開／下書きの対象範囲、アセット、リレーションシップの種類。
• 移行元から Sanity へのマッピング：ドキュメントの種類、オブジェクトの種類、参照、Portable Text フィールド、アセットフィールド、ID、移行対象外のコンテンツ。
• 抽出方法：必要な認証情報／アクセス権、API／エクスポートコマンド、生データスナップショットの保存場所、既知の見落とし。
• 変換／インポート計画：決定的な ID、書き込み順序、アセットの扱い、リッチテキストの変換、検証、再実行の方針。
• 切り替え計画：差分同期／コンテンツの凍結、リダイレクト、リンク切れのチェック、SEO メタデータ、手動でのクリーンアップ。

デフォルト設定

• 移行元の ID、スラッグ、パス、またはハッシュから安定したドキュメント ID を生成します。
• 再実行しても収束するよう、createOrReplace、createIfNotExists、または sanity datasets import --replace を使用します。
• 変換の前に、抽出した移行元データをディスクにスナップショットとして保存します。
• 参照されるドキュメントを、参照するドキュメントより先にインポートまたは作成します。
• リッチテキストは Portable Text に変換し、生の HTML 文字列や Markdown 文字列として保存しないでください。
• アセットは Sanity または Media Library にアップロードします。本番コンテンツを旧 CDN の URL に依存させないでください。
• ドキュメントごとの品質上の問題を記録し、切り替え前に検証結果の概要を作成します。
• リダイレクト、QA、将来のデバッグに備えて、旧 URL と移行元の ID を保持します。

Sanity のガードレール

• 古いサイトでの表示方法ではなく、コンテンツが何であるかをモデル化します。
• 再利用するエンティティや個別に管理するエンティティにはドキュメントを使用し、1 つのドキュメントが所有するコンテンツにはオブジェクトを使用します。
• Sanity スキーマを作成する場合は、defineType、defineField、defineArrayMember を使用します。
• 旧 CDN の URL ではなく、アップロード済みの Sanity アセットまたは Media Library アセットを使う画像／ファイルフィールドを使用します。
• リッチテキストやカスタムブロックには Portable Text の配列を使用し、正規の本文として生の HTML を保存しないでください。
• TypeScript を使用するプロジェクトでは、スキーマまたは GROQ クエリを変更した後に、スキーマ抽出と TypeGen を実行します。
• 対象データセットに対して MCP／コンテンツツールを使用する前に、スキーマのデプロイまたは適用を済ませます。

Sanity の実装についてさらに詳しいガイダンスが必要な場合は、すでに利用可能であれば sanity-best-practices を使用してください。インストールされていない場合は、次のコマンドで追加できることをユーザーに伝えてください。

npx skills add sanity-io/agent-toolkit --skill sanity-best-practices

作業を止めて確認する

次の点が不明な場合は、コーディングを始める前に作業を止めて確認してください。

• 移行元へのアクセス方法、認証情報、エクスポートファイル、またはデータベース接続。
• 移行先の Sanity プロジェクト／データセット、またはスクラッチデータセットを使用するかどうか。
• 下書き、アーカイブ済み、予約公開、ロケール、またはバージョン履歴の対象範囲。
• メディアファイルを移行するかどうか、およびアセットの URL／ファイルにアクセスできるかどうか。
• 移行先のスキーマがすでに存在するか、または移行の一環として設計するかどうか。

やってはいけないこと

• ソースに基づくドキュメントにランダムな ID を作成しないでください。
• 参照先のドキュメントを取得してから作成しないでください。決定論的な ID と createIfNotExists／createOrReplace を使用してください。
• NDJSON やスクリプトが適切な場合、MCP コンテンツツールを使って一括移行を実行しないでください。
• 要求されていない限り、ロケールのフォールバック値を翻訳にそのまま含めないでください。
• 必須のメディア、著者、参照、リッチテキスト変換について、TODO を残さないでください。
• 件数チェック、サンプルチェック、参照チェック、ルート／リダイレクトのチェックを行わずに、移行が完了したと宣言しないでください。

参照マップ

移行に共通する原則については references/general.md を使用し、ソース固有の抽出方法、モデリング時の落とし穴、検証チェックについてはプラットフォーム別の参照資料を使用してください。

明示的に扱われていないソースシステムについては、references/general.md を適用し、最も近いプラットフォームのパターンに合わせてください。

• API ファーストの CMS：Contentful、Strapi、または Payload を参考にしてください。
• モノリシック型／ページビルダー型のシステム：WordPress、Drupal、Webflow、または AEM を参考にしてください。
• HTML を多く含むエクスポート：WordPress と Webflow のリッチテキストに関するガイダンスを参考にしてください。
• Markdown ファーストのソース：references/markdown.md を参考にしてください。