migrate-to-cloudcannon

CloudCannon への移行

このスキルでは、既存の SSG サイトを CloudCannon に完全移行するための作業を統括します。5 つのフェーズを調整し、ドメイン固有の作業は、単独でも使用できる個別のスキルに委任します。

モデルの推奨事項： 移行では、5 つのフェーズにわたる複数ファイルのアーキテクチャ上の判断が必要です。最良の結果を得るには、高度な推論ができるモデル（高速・軽量モデルではないもの）を使用してください。

必須： 移行はこのスキルをオーケストレーターとして実行してください。Phase 1 の前に orchestration.md を読み、各フェーズをサブエージェントに割り当て、ユーザーとの会話は自分で続けてください。サブエージェントを利用できない環境では、各フェーズを順番に自分で実行してください。

使用する場面

• 既存の SSG サイトを CloudCannon でエンドツーエンドに動作させる必要がある
• サイトテンプレートを CloudCannon 対応にする必要がある
• タスクの一環としてサイトを生成し（例：WordPress から）、CloudCannon に対応した状態にする必要がある

使用しない場面

• サイトはすでに CloudCannon 上にあり、機能を 1 つ追加する必要がある — cloudcannon-configuration、cloudcannon-snippets、または cloudcannon-visual-editing の機能別スキルに直接進んでください
• 多言語化または翻訳作業のみが必要 — make-site-multilingual、次に translate-site を使用してください。どちらも 5 つのフェーズには含まれません。
• 稼働中のサイトで CloudCannon の機能が 1 つだけ正常に動作しない — 全体を移行するのではなく、その機能を担当する機能別スキルを使用してください

内容

ファイル	内容
SKILL.md（このファイル）	5 つのフェーズ、引き継ぎ準備、命名規則、よくある間違い
astro/overview.md	Astro の場合はここから開始 — フェーズごとのガイド
hugo/overview.md	Hugo の場合はここから開始 — フェーズごとのガイド
eleventy/overview.md	Eleventy の場合はここから開始 — フェーズごとのガイド
audit.md	共通の監査ルール — 静的ページの分類
page-building.md	ページの調査で pages コレクションまたはページビルダーへの割り当てが必要な場合に読む
cc-friendly-conventions.md	共通 UI の処理に関する表
orchestration.md	サブエージェントでのフェーズ実行、質問、検証、規模の見積もり
handoff.md	ユーザーへの完了報告 — 誰が何をテストするか、確認事項
reading-order.md	各フェーズで読むドキュメントと、読み飛ばすタイミング
scripts/README.md	決定的な手順を自動化するスクリプト

対応している SSG

SSG	ガイド
Astro	astro/overview.md
Hugo	hugo/overview.md
Eleventy	eleventy/overview.md

上流スキルとの連携

このタスクの一環としてサイトを生成する場合（例：WordPress から変換する場合）、スキャフォールディングの前に、対象となる SSG のスキャフォールディング規約を確認します。Astro の場合は、astro/cc-friendly-conventions.md を参照してください。移行をスムーズに進めるための構造上の選択について説明しています。スキャフォールディングが完了したら、ここに戻って移行フェーズを実行します。

手順 1：SSG を検出する

プロジェクトのルートから実行します。

npx @cloudcannon/cli configure detect-ssg

検出した SSG に応じて、上記の適切なガイドを選びます。

移行フェーズ

各 SSG ガイドでは、以下の順番で進めます。単独のスキルに委任するフェーズには、以下で印を付けています。

1. 監査 — 変更を加える前に、コンテンツの構造、コンポーネント、ルーティング、ビルドパイプラインを分析します。
2. 設定 — CloudCannon の設定ファイルを生成してカスタマイズします。
   • cloudcannon-configuration スキルを読みます。
   • コンテンツでコンポーネント（MDX コンポーネント、Hugo または Eleventy のショートコード）やインライン HTML を使用している場合は、cloudcannon-snippets スキルも読みます。
3. コンテンツ — 必要に応じて、CMS で扱いやすい形式にコンテンツファイルを再構成します。
4. ビジュアル編集 — CloudCannon の Visual Editor 用に編集可能な領域を追加します。
   • cloudcannon-visual-editing スキルを読みます。
5. ビルドとテスト — 移行全体が問題なく完了したことを検証します。

すべてのサイトで全フェーズが必要とは限りません。小規模なサイトでは、コンテンツがすでに適切に構造化されている場合、フェーズ 3 を省略できます。フェーズ 4 は任意ですが、非常に有用です。

フェーズごとのワークフロー

フェーズのサブエージェントが手順 1〜4 を実行し、オーケストレーターが手順 5 を実行します。orchestration.md を参照してください。

1. 読み込む — ファイルに触れる前に、フェーズのドキュメントを最初から最後まで読みます。
2. 追跡する — ホストのタスク／TODO ツールを使い、フェーズのドキュメント内のチェックリスト項目ごとにタスクを 1 つ作成します。ツールがない場合は、フェーズの移行メモにチェックリストを記録し、そこで項目を完了済みにします。タスクを開始する前に in_progress に設定し、チェックリスト項目を満たした場合にのみ completed にします。フェーズの最後にタスクをまとめて完了にしないでください。
3. 作業する — フェーズをまたぐ小規模で機械的な修正（不足しているフィールドの追加、値の正規化など）は、どのフェーズでも行えます。それぞれの修正を引き継ぎに記載してください。構造上の変更（ファイルの移動、コレクションの再編成、レンダリングの変更）は、適切なフェーズで行います。
4. 書き込む — .cloudcannon/migration/<phase>.md に調査結果を記載し、後のフェーズが参照する次の 2 つのセクションも追加します。
   • 決定事項と理由 — 各選択とその理由を記載し、後のフェーズで再検討せずに従えるようにします。
   • 未解決の質問 — ユーザーへの、作業を妨げない質問と、それぞれに対して採用したデフォルトを記載します。
5. 引き継ぎ準備状況の確認 — 下記の引き継ぎ準備状況の行を、オーケストレーターまたは新たな検証担当者が、orchestration.md § Verification に従って確認します。そのフェーズを担当したサブエージェント自身が確認してはいけません。

理由： チェックリストにより、エージェントが見落としがちな項目（collections_config にないデータコレクション、参照されているデータファイルに対する data_config エントリの不足、ページビルダーのブロックに集中するあまりスキップされたブログ／詳細ページの編集可能領域、構造にリンクされていない配列）を見つけられます。項目ごとに進捗を追跡することで、見落としを可視化できます。

フェーズ引き継ぎの準備状況

これらの行は、次のフェーズのサブエージェントが開始する前に満たしておくべき条件を定義します。フェーズをまたぐ修正（上記の手順 3 など）は引き続き問題ありません。

フェーズ終了後	引き継ぎの準備が整った状態
1. 監査	.cloudcannon/migration/audit.md が存在し、調査一覧表を含み、すべてのコレクションとすべてのページルートを記載していること。サイズ基準（orchestration.md § Sizing）を評価済みであること。基準に該当した場合は、.cloudcannon/migration/plan.md が存在すること。
2. 設定	cloudcannon.config.yml が公開済みの JSON スキーマに準拠していること（IDE に赤い波線が表示されないこと）。監査対象のすべてのコレクションに collections_config エントリーがあり、参照されるすべてのデータファイルに data_config エントリーがあること。.cloudcannon/migration/configuration.md が作成されていること。
3. コンテンツ	フェーズ 2 で行ったコンテンツの構造的な変更が、すべてファイルに反映されていること。npm run build（またはプロジェクトに相当するコマンド）が成功すること。.cloudcannon/migration/content.md が作成されていること。
4. ビジュアル編集	編集可能な領域が必要か？ が「はい」の監査調査一覧の各行について、接続が完了しているか、接続しない理由が記録されていること。ラップされたセクション内で使用されるすべてのコンポーネントを再レンダリングできること（登録済み（Astro：registerComponents.ts）または解決可能（Hugo：パーシャル、Eleventy：Liquid インクルード。Nunjucks セクションではプリミティブ領域のみを使用））。.cloudcannon/migration/visual-editing.md が作成されていること。
5. ビルドとテスト	本番ビルドがローカルで成功すること。ユーザーが CloudCannon 側の検証（プレビュー、インライン編集、Git への保存）を実施済みであること。.cloudcannon/migration/build.md が作成されていること。

スクリプト

決定論的な移行手順は、scripts/ 内のスクリプトとして自動化されています。該当するフェーズの前または実行中に、これらを実行してください。

移行メモ

すべて .cloudcannon/migration/ に書き込みます（.cloudcannon/ の下に置くことで、CLI がこのフォルダーをコレクションとして検出しないようにします）。各フェーズにつき 1 ファイル（audit.md、configuration.md、content.md、visual-editing.md、build.md）を作成し、移行を複数セクションに分ける場合は plan.md も作成します。各ファイルを使用するゲートについては、上記のフェーズ別ワークフローを参照してください。

命名規則

既存のプロジェクト規則がある場合は、それに従ってください。ない場合は、次の規則を使用してください。

• ファイルには kebab-case
• JavaScript と JSON には camelCase
• Markdown のフロントマターと YAML：フロントマターのキーを翻訳せずにそのまま適用できるよう、既存のコンポーネントのプロパティ名に合わせる
• 既存の規則がない新しいフィールドには、snake_case を推奨

既知の落とし穴に関する相互参照

具体的なアーキテクチャ上の判断や設定構文の誤りについては、以下をご覧ください。

トピック	Astro	Hugo	Eleventy
静的ページの分類（ソース編集可能、ページビルダー、コレクション）	audit.md § 静的ページの分類、続いて astro/audit.md	hugo/audit.md § 静的ページの分類	eleventy/audit.md § 静的ページの分類
ホームページのファイル名、1 件のみのコレクション	page-building.md § よくある間違い、続いて astro/page-building.md § Pages コレクション早見表	hugo/page-building.md § よくある間違い	eleventy/page-building.md § よくある間違い
共通 UI（CTA バナー、フッター、共有ブロック）	cc-friendly-conventions.md § 共通 UI の扱いに関する表	同じ表	同じ表
複数スキーマのコレクション	../cloudcannon-configuration/astro/configuration.md § スキーマ	../cloudcannon-configuration/hugo/configuration.md § スキーマ	../cloudcannon-configuration/schemas.md
設定構文のハルシネーション（誤ったキー／型）	cloudcannon-configuration § 無効なキー	同じ	同じ
ビルド検証	build.md § ビルド検証チェックリスト、続いて astro/build.md	build.md、続いて hugo/build.md	build.md、続いて eleventy/build.md

Common mistakes

言い訳	実際のところ
「このサイトは単純なので、監査は省略しても大丈夫です」	監査を行うと、構造上の問題を早期に発見できます。省略すると、設定の途中で問題に気づくことになります。
「チェックリストは最後にやります」	各フェーズを開始する前に、チェックリストを確認してください。目指すべき内容がわかります。
「コンテンツの再構成は後回しで大丈夫です」	不足しているフィールドが設定の妨げになっている場合は、今すぐ追加してください。フェーズは順番に進めるもので、互いに独立しているわけではありません。
「ビジュアル編集は任意なので省略します」	エディターにとって、最も価値の高いフェーズです。ユーザーから明示的に指示された場合に限り、省略してください。
「ビルドが通ったので、これで完了です」	ビルドが通っても、エディターが動作するとは限りません。ユーザーがCloudCannonで確認する必要があります。
「ホームページのファイル名を home.md にします。こちらのほうが内容を表しています」	CloudCannonはスラッグからURLを解決します。url: "/[slug]/" を指定した home.md の場合、URLは /home/ になります。スラッグが / になるよう、SSGのインデックスファイル名を使用してください。Astro：index.md、Hugo：content/_index.md、Eleventy：入力ディレクトリ内の index.md。
「ハードコードされているので、開発者しか編集しません」	エディターがページ上で確認できるものは、編集できるようにする必要があります。仕組みはページによって異なります。共通UI（CTAバナー、フッター、共有ブロック、著者カード）→ データファイル。エディターがセクションを追加、削除、並べ替えするページ → ページビルダーの pages コレクションエントリー。長文の本文ページ → pages コレクションの default スキーマ。開発者が構造を管理し続ける単発ページ → data-editable="source"。cc-friendly-conventions.md § 共通UIの扱いに関する表とpage-building.md § ページビルダーを使用する場面を参照してください。
「このページは独自性があるので、ソース編集可能にするべきです」	独自性が判断基準ではありません。ページビルダーをデフォルトとし、ソース編集可能なページにするには、page-building.md § ページビルダーを使用する場面に記載されたすべての条件を満たす必要があります。
「エントリーが1つだけの homepage コレクションを作ります」	index.md を1つのエントリーとする pages コレクションを1つ使用してください。さらにエントリーを追加する場合は、our-team.md、about.md などを追加します。CloudCannonのコレクションでは、schemas: 設定を使って、またAstroではコンテンツ設定のZod z.union を使って、1つのコレクション内で複数のスキーマをサポートできます。../cloudcannon-configuration/schemas.mdを参照してください。
「ページが少ししかないので、ページビルダーは過剰です」	プロジェクトが独自のレイアウトを管理し、固有のレイアウトを持つページが2つ以上ある場合は、ページビルダーをデフォルトにしてください。テーマがレンダリングするページでは、そのテーマのモデルを使用します。audit.md § 静的ページの分類を参照してください。必要なのは、キャッチオールルートとブロックディスパッチャーです。Astro：[...slug].astro + BlockRenderer。Hugo：ページレイアウト内で content_blocks を range で反復。Eleventy：レイアウト内で content_blocks を for ループで反復。いずれも機械的な作業です。その利点は、エンジニアリングの支援なしで、エディターが新しいページを追加できることです。