migrating-to-cloudcannon

CloudCannon への移行

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

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

サポート対象の SSG

SSG	ガイド
Astro	astro/overview.md

上流スキルとの連携

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

ステップ 1：SSG を検出する

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

npx @cloudcannon/cli configure detect-ssg

検出された SSG に基づいて、上記の適切なガイドを選択してください。

移行フェーズ

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

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

すべてのサイトで全フェーズが必要になるわけではありません。コンテンツがすでに適切に構造化されている小規模なサイトでは、フェーズ 3 を省略できることがあります。フェーズ 4 は任意ですが、大きな効果があります。

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

各フェーズを順番に、以下のように進めます。

1. 読む — ファイルに手を加える前に、そのフェーズのドキュメントを最初から最後まで読んでください。
2. TaskCreate — そのフェーズのドキュメントにあるチェックリスト項目ごとに 1 つのタスクを作成します。作業を始める前にタスクを in_progress に設定し、チェックリスト項目を満たしたときにのみ completed にします。フェーズの最後にタスクをまとめて完了にしないでください。
3. 作業する — 複数フェーズにまたがる小規模で機械的な修正（不足しているフィールドの追加、値の正規化など）はどのフェーズで行ってもかまいません。構造上の変更（ファイルの移動、コレクションの再編成、レンダリングの変更）は、適切なフェーズまで待ってください。
4. 記録する — .cloudcannon/migration/<phase>.md に、判断、調査結果、ユーザーに確認してもらう必要がある事項を記録します。
5. 以下の引き継ぎ準備状況の項目を確認する。 条件を満たしていれば、そのフェーズは新しい会話に安全に引き継げます。実際に新しい会話を開始するかどうかは判断に委ねられます（以下の大規模な移行の分割を参照）。同じ会話内で続ける場合は、そのまま作業を進めてください。

理由： チェックリストを使うと、エージェントが読み飛ばしがちな項目（collections_config に含まれていないデータコレクション、参照先のデータファイルに対する data_config エントリの不足、ページビルダーブロックに注力するあまり見落とされるブログ／詳細ページの編集可能領域、ストラクチャにリンクされていない配列）を確認できます。TaskCreate を使うと、読み飛ばしが可視化されます。

フェーズ引き継ぎの準備

これらの行は、新しい会話でフェーズを安全に引き継ぐために満たすべき条件を定義しています。1つの会話内でフェーズ間を隔てる壁ではありません。上記の手順3に従ったフェーズをまたぐ修正も引き続き可能です。分割して進める移行の後続作業を、確実に開始できる状態にするためのものです。

フェーズ終了後	引き継ぎの準備が整っている状態
1. 監査	.cloudcannon/migration/audit.md が存在し、調査一覧表を含み、すべてのコレクションとすべてのページルートを記載していること。セクション分けのしきい値（以下）が評価済みで、しきい値を超えている場合は .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. ビジュアル編集	監査の調査一覧で「編集可能な領域が必要」としてマークされたすべてのセクションが接続されているか、接続しない理由が記録されていること。registerComponents.ts がラップされたセクション内で使用されるすべてのコンポーネントを登録していること。.cloudcannon/migration/visual-editing.md が作成されていること。
5. ビルドとテスト	本番ビルドがローカルで成功すること。ユーザーが CloudCannon 側の検証（プレビュー、インライン編集、Git への保存）を実行済みであること。.cloudcannon/migration/build.md が作成されていること。

大規模な移行を分割して進める

移行は1つの会話内で最初から最後まで進められますが、大規模なサイトではコンテキストがいっぱいになり、前のフェーズでの決定事項を長いやり取りから思い出す必要がある後続フェーズ（特にフェーズ4のビジュアル編集）で、品質が低下します。新しい会話に分けて進めることで、これを避けられます。

分割は提案であり、強制ではありません。 エージェントはフェーズ間で 停止 することはありません。ユーザーに「コンテキストが重くなっています。フェーズ N は新しい会話で始めることを検討してください」と伝え、選択をユーザーに委ねます。同じ会話を続けても問題ありません。

新しい会話への切り替えを提案するタイミング

フェーズ 1 の終了時に、.cloudcannon/migration/audit.md に対して規模のしきい値を評価します。

シグナル	しきい値	ソース
ページの合計数	> 30	Audit § Pages and routing
ハードコードされた .astro → YAML への変換	> 15	Audit の調査表で、page-builder または固定スキーマのコレクションが推奨されている行
個別のコレクション数	> 5	Audit § Content collections + 調査で追加されたコレクション

2 つ以上のしきい値に達した場合は、以下のテンプレートを使って .cloudcannon/migration/plan.md を作成し、後続のフェーズは新しい会話で実行するようユーザーに提案します。フェーズ 4（ビジュアル編集）は最も多くのコンテキストを必要とするため、新しい会話での実行が最も適しています。

形式	条件
垂直型（コレクションごと）	page-builder ページまたは独自の構造を持つコレクションが大半を占める場合 — 各単位に独自のスキーマやビジュアル編集の判断が必要です
水平型（フェーズごと）	コレクションの構造がほぼ均一な場合 — コレクションごとの反復作業は、一度に 1 つのメンタルモデルで進めると効率的です

.cloudcannon/migration/plan.md テンプレート

# Migration plan

## Sizing

- Total pages: <n> (threshold >30: <tripped|ok>)
- Hardcoded → YAML conversions: <n> (threshold >15: <tripped|ok>)
- Distinct collections: <n> (threshold >5: <tripped|ok>)
- Tripped: <count>/3 → <chunked recommended|single-pass fine>

## Shape (if chunking)

<vertical|horizontal> — because: <one-line reason>

## Chunks

Each chunk is intended as a single agent run, ideally in a fresh conversation
once context is heavy. The agent reads `.cloudcannon/migration/audit.md` + this file + the
listed phase doc, then works the listed scope.

| #   | Scope                            | Phase(s) | Inputs                     | Output artefact                           |
| --- | -------------------------------- | -------- | -------------------------- | ----------------------------------------- |
| 1   | <e.g. all collections — config>  | 2        | audit.md                   | cloudcannon.config.yml + configuration.md |
| 2   | <e.g. blog collection — content> | 3        | audit.md, configuration.md | content.md (blog section)                 |
| 3   | <...>                            | ...      | ...                        | ...                                       |

## Global decisions locked in chunk 1 (do not revisit)

- Collection URL patterns
- Shared structures (`_structures`)
- Snippet configs (if MDX/inline HTML)
- `registerComponents.ts` setup

再開時の概要（新しい会話に貼り付けます）：「.cloudcannon/migration/audit.md、.cloudcannon/migration/plan.md、およびチャンク N に記載されたフェーズのドキュメントを読みます。チャンク N の範囲を作業し、成果物を出力したら終了してください。」

反復作業 → スクリプト化のルール： 同じ構造のエントリーを 2 件移行したら、残りを処理する使い捨てスクリプトを作成します。同じ記事の構造を 23 件手作業で変換するのは、トークンの無駄であり、エラーを増やす要因になります。

スクリプト

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

移行メモ

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

引き継ぎと検証

テストの分担

チェック	担当者
ローカルビルド（npm run build または package.json で定義されたコマンド）	エージェント
ビルド、grep、小規模なスクリプト、dist/ の確認	エージェント
CloudCannon での忠実性チェック（プレビュー、インライン編集、Git への保存）	人間

エージェントのセッションで長時間稼働する開発サーバーを起動したり、負荷の高いエンドツーエンドテストを実行したりするより、CloudCannon での検証をユーザーに依頼してください。

ユーザーとの作業を終えるタイミング

些細な編集のたびではなく、意味のある単位の作業が終わったら完了とします。最低限、初回の移行全体でフェーズ 5（ビルドとテスト）が完了した時点が目安です。ユーザーがそれより前（たとえば設定だけの段階）で作業を止める場合は、その時点で引き継いでください。

伝える内容

簡潔に、要点を伝えます。

1. 変更内容の簡単な概要。
2. ユーザーが実行できるチェックリスト。
3. フィードバックを求める明確な依頼を 1 つ。

空疎な表現（「何か必要なことがあればお知らせください」など）は避けます。確認へのお礼を一度伝えるのは問題ありません。

ユーザーに確認を依頼する項目

• ローカルビルド — 部分的なコマンドではなく、プロジェクトで実際に使うビルドのエントリーポイントを確認してください。失敗した場合は、エラー出力全体（コマンド、終了コード、標準エラー出力の最後の約30行）を貼り付けてください。
• 実行済みのチェック — ユーザーが作業を重複して行わないよう、実行済みのチェックを1行で記載してください。
• CloudCannon（人による確認） — ホスト環境で次の項目を確認してください。
  • 代表的なページのプレビューでインラインのテキスト領域を編集できる
  • 画像領域をクリックすると画像ピッカーが開く
  • 配列が設定されている箇所では、配列領域に追加、削除、並べ替えのコントロールが表示される
  • ファイルをまたぐ編集可能項目（@file、共有パーシャル）によって、意図したソースファイルが更新される
  • 保存した変更が、git の想定したファイルに反映される

ユーザーに返送を依頼する情報

具体的な情報を依頼してください。実行した正確なコマンド、リモートビルドに失敗した場合の CloudCannon ビルドログの抜粋、エディターが正しく動作しなかった場合のページ URL とクリックした箇所、または想定と異なる点の簡単な説明です。

反復

最後に、次の作業に進めるよう1行で促してください。これらのチェックを実行した後、失敗や予期しない動作があれば返信してもらいます。

命名規則

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

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

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

特定のアーキテクチャ上の判断や設定構文の誤りについては、以下を参照してください。

トピック	担当
静的ページの分類（ソース編集可能ページ vs ページビルダー vs コレクション）	astro/audit.md § 静的ページの分類
home.md と index.md の違い、1件のみのコレクション	astro/page-building.md § よくある間違い
共有 UI（CTA バナー、フッター、共有ブロック）	astro/cc-friendly-conventions.md § 共有 UI の扱いに関する表
複数スキーマのコレクション（pages と z.union）	../cloudcannon-configuration/astro/configuration.md § スキーマ
設定構文のハルシネーション（誤ったキー／型）	cloudcannon-configuration § よくある無効なキー
prose prose-lg クラスがあるのに、Markdown の本文がスタイルなしのテキストとして表示される — 見出しのサイズ、リストの箇条書き、リンクの色が反映されない	@tailwindcss/typography がインストールされていないか、登録されていません。Tailwind 4 では、メイン CSS の @import "tailwindcss"; の後に @plugin "@tailwindcss/typography"; が必要です。2行で修正できます。npm install @tailwindcss/typography を実行し、@plugin ディレクティブを追加します。

よくある間違い

言い訳	実際
「このサイトはシンプルなので、監査は省略しても問題ありません」	監査によって構造上の問題を早期に発見できます。省略すると、設定の途中で問題を発見することになります。
「チェックリストは最後に確認します」	各フェーズを始める前に、チェックリストを確認してください。目指すべき内容が示されています。
「コンテンツの再構成は後回しでかまいません」	不足しているフィールドが設定の妨げになる場合は、今すぐ追加してください。各フェーズは順番に進めるもので、互いに独立しているわけではありません。
「ビジュアル編集は任意なので省略します」	編集者にとって、最も価値の高いフェーズです。ユーザーから明示的に指示された場合にのみ省略してください。
「ビルドに成功したので完了です」	ビルドに成功しても、編集者が問題なく作業できるとは限りません。ユーザーは CloudCannon で確認する必要があります。
「ホームページのファイル名は home.md にします。そのほうが内容がわかりやすいので」	CloudCannon はスラッグから URL を解決します。url: "/[slug]/" を指定した home.md は /home/ になります。Astro がスラッグを / にまとめるよう、index.md を使用してください。
「ハードコードされているので、開発者しか使いません」	編集者がページ上で確認できる内容は、編集できる必要があります。仕組みはページによって異なります。共有 UI（CTA バナー、フッター、共有ブロック、著者カード）→ データファイル、2 つ以上のセクションがある独自レイアウトのページ → ページビルダーの pages コレクションエントリー、長文の文章ページ → 本文に Markdown を含む固定スキーマのコレクションです。data-editable="source" は長文の文章専用であり、単発の文字列に使うデフォルトの方法ではありません。astro/cc-friendly-conventions.md § 共有 UI の扱いに関する表 と astro/page-building.md § ページビルダーを使う場面 を参照してください。
「このページは独自のものなので、ソースを編集できるようにすべきです」	2 つ以上のセクションがある独自レイアウトのページは、ページビルダーのスキーマを備えた pages コレクションに含めます。ソース編集は長文の文章専用です。astro/audit.md § 静的ページの分類 を参照してください。
「エントリーが 1 つだけの homepage コレクションを作ります」	index.md を 1 つのエントリーとして含む pages コレクションを使用してください。our-team.md、about.md などを追加のエントリーとして加えます。CloudCannon のコレクションは、schemas: の設定と Astro のコンテンツ設定にある Zod の z.union の両方を使って、1 つのコレクションに複数のスキーマを設定できます。../cloudcannon-configuration/astro/configuration.md § スキーマ を参照してください。
「この数ページにページビルダーを使うのは大げさです」	独自レイアウトのページが 1 つより多いサイトでは、ページビルダーをデフォルトで使用します。必要なのは [...slug].astro のキャッチオールと BlockRenderer だけで、どちらも定型的な作業です。その代わり、編集者はエンジニアに頼らず新しいページを追加できます。