microCMS

View saved version →

---
name: microcms-docs
description: microCMSの公式開発者ドキュメント(document.microcms.io)を取得し、API仕様・制限・認証・クエリ・管理画面の操作手順を出典付きで確認する。最新の仕様確認や公式資料・コード例の参照が必要な場合に使用する。プロジェクトの設計・実装・改善はmicrocms-guide、Next.js固有の実装はmicrocms-nextjsを優先し、必要な仕様確認をこのSkillで補う。
license: MIT
---

# microCMS ドキュメント参照スキル

## 概要

microCMS公式開発者ドキュメント `document.microcms.io` に対し、ユーザーの質問に応じた適切なページを特定し、Web取得ツールで内容を取得して回答する。記憶や推測ではなく、常に最新のドキュメントを根拠とする。

## 他のSkillとの使い分け

公式情報の取得と根拠の確認を担当する。設計・実装・改善を進める依頼では、利用可能なら `microcms-guide` または `microcms-nextjs` を使い、必要な仕様確認だけをこのSkillで補う。別Skillが未導入でも資料参照を続ける。Skill名の記載だけで別Skillが自動的に読み込まれるとは想定しない。

## ワークフロー

### 1. 質問の分類

ユーザーの質問が次のどのカテゴリに該当するかを判断する:

| カテゴリ | 想定される質問 |
|---------|-------------|
| コンテンツAPI | データ取得/登録、クエリパラメータ、APIキー、エラー対応 |
| マネジメントAPI | コンテンツの管理操作、メディア操作、メンバー取得 |
| 画像API | リサイズ、フォーマット変換、ウォーターマーク |
| 操作マニュアル | 管理画面の使い方、フィールド設定、Webhook設定、権限 |
| チュートリアル | Next.js/Nuxt/Astro等のフレームワーク統合 |
| SDK | 各言語SDKの使い方、コード例 |

複数カテゴリにまたがる場合（例: 「Next.jsで下書きプレビューを実装する」）は、関連する全カテゴリのURLを参照する。

### 2. URLの特定

`references/urls.md` を読み、関連URLを特定する。**URLを推測で生成してはならない**。

`urls.md` に該当ページが無い場合は、公式のページ一覧 `https://document.microcms.io/llms.txt` を取得して探す。全ページのタイトルとMarkdown版URLが列挙されているため、`urls.md` の記載が古い場合でもここから正しいURLを特定できる。

`llms.txt` にも該当が無ければ、そのページは存在しない。パスを組み立てて試すのではなく、「ドキュメントに該当ページが見つからない」ことをユーザーに伝える。

### 3. ドキュメントの取得

特定したURLの**末尾に `.md` を付与して取得する**。取得には、利用中のエージェントが持つWeb取得の手段（Web取得ツール、`curl` など）を使う。`.md` 付きでアクセスすると `text/markdown` 形式で本文が返るため、HTMLパース不要でLLMが扱いやすい。

例:
- HTML版: `https://document.microcms.io/content-api/get-list-contents`
- **Markdown版（こちらを使う）**: `https://document.microcms.io/content-api/get-list-contents.md`

複数URLが必要な場合は、可能な限り**まとめて取得する**（並列取得に対応した環境では並列で取得する）。

> [!IMPORTANT]
> 存在しないパスでも 404 ではなく **200 で HTML が返る**ことがある。取得結果が Markdown 本文ではなく HTML だった場合、そのURLは無効と判断する。内容を推測で補ってはならない。
> その場合は `https://document.microcms.io/llms.txt` を取得し、正しいURLを探し直す（ページがリネームされ `urls.md` の記載が古くなっている可能性がある）。
> セクションのトップURL（`/tutorial/next/` など）は `.md` に対応していないため、`urls.md` に列挙された実ページのURLを使う。

取得時は、そのページから何を読み取りたいのかを明確にしてから読む:
- コード例が欲しい場合: コード例（特に該当箇所）を抽出する
- 仕様確認: パラメータ仕様、デフォルト値、必須/任意を一覧化する
- 手順確認: 目的の操作を行うための手順を順番に抽出する

### 4. 回答の生成

取得した内容に基づいて回答する。以下を遵守する:

- **出典URL を必ず明示する**（複数あれば全て）
- **コード例はドキュメントの内容に基づき**、不足部分のみ補完する
- ドキュメントに記載がない事項は「ドキュメントに明示されていない」と明確に伝える
- 古い情報（例: 旧APIキー方式）と新しい情報（`X-MICROCMS-API-KEY`）が混在する場合は、新しい方を推奨し旧方式の存在に触れる

## 重要な注意事項

1. **URLは必ず `references/urls.md` から確認**。`/manual/foo` のようなパスを記憶や類推で組み立てない。
2. **取得時はURL末尾に `.md` を付与する**。Markdown形式で本文が返り、HTML版より精度・効率が向上する。
3. **ベースURLは `https://document.microcms.io`**。`docs.microcms.io` や `microcms.com/docs` 等の類似URLは存在しない（誤記の可能性）。
4. **APIエンドポイント**: コンテンツAPIは `https://{service-id}.microcms.io/api/v1/{endpoint}`、マネジメントAPIは `https://{service-id}.microcms-management.io/api/v1/`。
5. **認証**: 現行は `X-MICROCMS-API-KEY` ヘッダー。旧 `X-API-KEY` は非推奨。
6. **言語**: ドキュメントは日本語版が主。英語版が必要な場合のみ、パス先頭に `/en` を付ける（例: `/en/content-api/introduction.md`）。
7. **チュートリアルの対応範囲**: Next.js / Astro / Nuxt 2 / Gatsby / JavaScript / PHP / Ruby / Go の8種類のみ。Remix / Nuxt 3 / iOS / Android のチュートリアルページは存在しないため、質問された場合はその旨を伝え、コンテンツAPIの仕様や各SDKのリポジトリを案内する。

## ユーザーへの確認

以下のような場面ではユーザーに確認し、判断を仰ぐ:

- 質問が曖昧で複数のカテゴリに該当しうる場合（例: 「画像を扱いたい」→ 画像API or 画像フィールド or メディア管理？）
- 利用フレームワーク/SDKが特定できず、複数のチュートリアルから選ぶ必要がある場合
- 提示する情報量や形式に選択肢がある場合（コード例のみ／詳細解説込みなど）

## リソース

- `references/urls.md`: 主要URL一覧（カテゴリ別、簡易説明付き）とクエリパラメータ早見表。まずこれを参照する。
- `https://document.microcms.io/llms.txt`: 公式が提供する全ページ一覧（約13KB）。`urls.md` で見つからないとき、または取得結果がMarkdownでなかったときのフォールバックとして取得する。

> [!CAUTION]
> `https://document.microcms.io/llms-full.txt` は全ページの本文を結合したファイルで **750KB 以上**ある。取得してはならない。
> `llms.txt` の取得に失敗した場合は `urls.md` の情報だけで回答を続ける。

## 関連

公式が `microcms-document-mcp-server` を提供している（`/mcp-server/microcms-document-mcp-server`）。利用可能な環境では併用するとさらに効率的。

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: microcms-guide
description: microCMSの設計・実装・改善を公式情報に基づいて支援する。初期設定、コンテンツモデリング、Content API、microcms-js-sdk、画像API、転送量削減、プレビュー、Webhookの相談や、利用方法が未確定な依頼で使用する。Next.js固有のルーティング・キャッシュ実装はmicrocms-nextjsを優先する。
license: MIT
---

# microCMS Guide

microCMSの公式な概念、推奨パターン、ユーザーのプロジェクト状況を踏まえて、ユーザーがmicroCMSを使ったタスクを完了できるよう支援する。一般的な製品説明より、具体的で実行可能な案内を優先する。

原則として日本語で回答する。ユーザーが別の言語を指定した場合は、その指定に従う。

## 基本方針

1. ユーザーがmicroCMSを使って何を実現したいのかを特定する。
2. 既存のプロジェクト、コード、設定、APIスキーマが利用可能な場合は、提案の前に確認する。
3. タスクに必要なリファレンスだけを読み込む。
4. ユーザーの要件を満たす最もシンプルな方法を推奨する。
5. 複数の妥当な方法がある場合は、重要なトレードオフを説明する。
6. 必要に応じて、具体的な実装方法、コード例、次のアクションまで提示する。
7. フレームワーク固有の詳細実装は、利用可能な場合は対応する専門Skillに委ねる。

ユーザーがmicroCMSそのものの概要説明を求めている場合を除き、「microCMSとは何か」の一般的な説明から始めない。

## 情報の扱い

公式開発者ドキュメントの取得・仕様確認には、利用可能なら `microcms-docs` を併用する。設計判断や実装はこのSkillで進め、必要なページだけ確認する。未導入の場合は各referenceの公式出典を直接確認する。

目的に応じて、次の公式情報を使い分ける。現在のタスクに必要な情報だけ確認する。

| 参照先 | 主な役割 |
| --- | --- |
| [公式ドキュメント](https://document.microcms.io/) | 機能・APIの仕様、パラメータ、管理画面の操作方法 |
| [公式ナレッジサイト](https://help.microcms.io/ja/knowledge) | 実装上の注意点、運用上の判断、トラブルシューティング |
| [公式料金ページ](https://microcms.io/pricing) | プランごとの機能提供範囲、上限、料金、追加オプション |

料金の比較や、API数・メンバー数・権限管理・複数環境など、提案の実現可否がプランに依存するときは公式料金ページを確認する。通常のAPI実装など、プランに依存しない作業で毎回読む必要はない。

利用中のプランや個別の契約条件が分かる場合は、それも踏まえる。金額・上限値・機能比較表をSkillへ固定的に転載せず、回答時に確認した公式ページを出典として示す。確認できない項目は金額や利用可否を断定しない。料金ページの「APIリクエスト数」と、API仕様上のレート制限・レスポンスサイズ制限は別に確認する。

- ナレッジサイトの記事のサンプルは対象バージョンと適用条件を確認し、回避策を全プロジェクト共通の必須設定にしない。
- 同梱リファレンスは判断の手引きとして使う。各ファイル末尾の公式情報を仕様の根拠とし、同梱内容と利用中バージョンの公式情報が矛盾する場合は公式情報を優先する。
- microCMSの機能、APIの挙動、SDKオプション、制限、料金プラン上の提供範囲などを推測で補わない。
- microCMSが提供する挙動と、フレームワーク、ホスティングサービス、ブラウザ、CDN、その他外部サービスが提供する挙動を区別する。
- 同梱内容の有無にかかわらず、変更されうる仕様・SDKの対応バージョン・制限・料金については、利用可能なツールで公式情報を確認する。確認できない場合は最終確認時点の案内であることと未確認事項を明示する。
- 明確な理由がない限り、ユーザーの既存アーキテクチャを維持する。
- APIキーは付与された権限と利用場所をセットで判断する。書き込み権限、下書き取得、非公開APIへのアクセスなどを含むキーやDraft Keyなどの秘密情報は、リポジトリやクライアントサイドへ露出させない。CSRでAPIキーを利用する場合は、公開して問題のないAPIに対する必要最低限のGET権限へ制限する。

## フレームワーク固有の処理を振り分ける

このSkillでは、フレームワークに依存しないmicroCMSの知識とベストプラクティスを扱う。

詳細なフレームワーク固有の実装が必要な場合は、利用可能であれば対応する専門Skillを使用する。

例：

- Next.js固有のデータ取得、キャッシュ、ISR、Draft Mode、ルーティング、`next/image`などは `microcms-nextjs` を使用する。

専門Skillは必要な場合だけ併用する。Skill名を書くだけで別Skillが自動的に読み込まれるとは想定せず、利用環境で取得できる関連リファレンスを明示的に読む。

対応する専門Skillが利用できない場合は、確実に説明できる範囲でのみフレームワーク固有の案内を行い、未確認のフレームワーク挙動をmicroCMSの仕様として説明しない。

## 必要なリファレンスだけを読み込む

現在のタスクに関連するファイルのみを読み込む。

- **はじめ方・基本概念**: サービス、API、コンテンツ、APIキー、コンテンツAPIの基本的な利用方法については [references/getting-started.md](references/getting-started.md) を読む。
- **コンテンツモデリング**: APIスキーマ設計、リスト形式・オブジェクト形式、コンテンツ参照、カテゴリ、タグ、著者、繰り返しフィールド、カスタムフィールドの複雑さ、スキーマ保存時のバリデーションエラーについては [references/content-modeling.md](references/content-modeling.md) を読む。
- **JavaScript SDK**: `microcms-js-sdk`、クライアント設定、コンテンツ取得メソッド、queries、TypeScript、検索の選択、繰り返しのPATCH、リトライ、リクエスト設定については [references/js-sdk.md](references/js-sdk.md) を読む。
- **画像API**: 画像のリサイズ、トリミング、フォーマット・品質調整、レスポンシブ配信、画像に起因するデータ転送量削減については [references/image-api.md](references/image-api.md) を読む。
- **パフォーマンス**: APIリクエスト効率、取得フィールドの最適化、キャッシュ、データ転送量削減、CDNキャッシュ条件、429・5xxの診断については [references/performance.md](references/performance.md) を読む。
- **プレビュー**: Draft Key、プレビューURL、下書きコンテンツの取得、フレームワーク非依存のプレビュー概念については [references/preview.md](references/preview.md) を読む。
- **Webhook**: ビルド、キャッシュ更新、外部サービス連携などのイベント駆動処理やWebhook設計については [references/webhooks.md](references/webhooks.md) を読む。

複数の観点にまたがる場合は、必要なリファレンスを組み合わせる。たとえば、画像によるデータ転送量を減らしたい場合は `image-api.md` と `performance.md` の両方を使用する。

## ユーザーの目的から提案する

機能を列挙するのではなく、ユーザーの目的を起点に案内する。

例：

- 「データ転送量を減らしたい」場合は、まず転送量の主な発生源を特定する。アーキテクチャ変更を提案する前に、画像配信、不要に大きなAPIレスポンス、重複したリクエスト、キャッシュ状況を確認する。
- 「ブログのAPIスキーマを設計したい」場合は、必要なコンテンツ間の関係と編集運用を確認し、要件を満たす最小限のコンテンツモデルを提案する。
- 「JavaScriptでコンテンツを取得したい」場合は、実装を簡潔にできるなら `microcms-js-sdk` を推奨し、コンテンツAPIへ直接リクエストする方法で十分なケースとの違いも説明する。
- 「未公開コンテンツをプレビューしたい」場合は、まずmicroCMS側のプレビューの仕組みを説明し、その後のフレームワーク固有実装は対応する専門Skillに委ねる。

## 既存プロジェクトを扱う

コードやプロジェクトファイルを確認できる場合は、以下の順序で進める。

1. 新しいコードを生成する前に、現在の実装を確認する。
2. タスクに関連する既存のmicroCMSクライアント、環境変数、API呼び

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 8 — file references are metadata, not package contents.

View saved version →

---
name: microcms-nextjs
description: Next.jsとmicroCMSの連携を公式情報に基づいて実装・改善する。SDKセットアップ、App Routerのデータ取得・動的ルート、キャッシュ・ISR・Webhook、Draft Mode、next/imageの実装や不具合調査で使用する。フレームワーク非依存のAPI仕様・コンテンツ設計のみの相談はmicrocms-guideを優先する。
license: MIT
---

# microCMS + Next.js

Next.jsプロジェクトでmicroCMSを適切に利用できるよう、既存コード・Next.jsのバージョン・キャッシュ構成を確認しながら具体的な実装まで支援する。

原則として日本語で回答する。ユーザーが別の言語を指定した場合は、その指定に従う。

## 基本方針

1. 既存プロジェクトが利用可能なら、コードを生成する前に構成を確認する。
2. Next.jsのバージョン、App Router / Pages Router、`cacheComponents` の有無を確認する。
3. ユーザーが求める更新反映時間、静的生成の必要性、プレビュー要件を確認する。
4. microCMS共通の詳細は、`microcms-guide` が利用可能なら関連リファレンスのみを読む。未導入・未読でも、このSkill内の説明と各リファレンスの公式情報から作業を進める。別Skillの自動読み込みを前提にしない。
5. 新規の例ではApp Routerを基本とするが、既存プロジェクトがPages Routerなら無理に移行させない。
6. APIキーはサーバー側で扱い、書き込み・下書き全取得・非公開データへアクセスできるキーをブラウザへ渡さない。CSRで直接取得する要件がある場合のみ、公開可能なAPIへのGET専用キーを検討する。Draft Keyも秘密情報として扱う。
7. Next.jsのキャッシュ仕様はバージョン依存性が高いため、古いパターンを機械的に適用しない。

## 最初にプロジェクト状態を判定する

キャッシュ・データ取得・Draft Modeに関する作業では、可能なら次を先に確認する。

- `package.json` の `next` バージョン
- `app/` または `src/app/` の有無
- `pages/` または `src/pages/` の有無
- `next.config.*` の `cacheComponents` 設定
- `microcms-js-sdk` のバージョン
- microCMSクライアントの作成場所
- APIキーの環境変数名
- ホスティング先と実行Runtime
- `output: 'export'` の有無（静的エクスポートではサーバー上のISR・Draft Mode・Webhook受信は実行できない）
- 既存の `revalidate`、`revalidatePath`、`revalidateTag`、`use cache`、`cacheLife`、`cacheTag` の利用状況

これらをコードから確認できる場合、ユーザーへ同じ情報を質問しない。

## Next.js 16以降のキャッシュモデルを区別する

Next.js 16では `cacheComponents: true` を有効にした場合と、従来のキャッシュモデルで設計が異なる。

- `cacheComponents: true` の場合は `use cache`、`cacheLife`、`cacheTag` を中心に考える。
- `cacheComponents` を利用していない場合は、`fetch` の `cache` / `next.revalidate`、Route Segment Config、`revalidatePath` / `revalidateTag` など従来モデルを確認する。

`export const revalidate = 60` をすべてのNext.jsプロジェクトへ無条件に提案しない。

詳細は [references/caching.md](references/caching.md) を読む。

## Server Componentsを基本にする

App RouterでmicroCMSの公開データをページ表示に使う場合は、特別な理由がなければServer Componentからサーバー側で取得する方法を第一候補にする。

以下の理由だけでClient Componentへしない。

- microCMSを使っているから
- API取得があるから
- ページ内に一部インタラクションがあるから

クライアント側の状態・イベント・ブラウザAPIが必要な部分だけをClient Componentへ分離する。

Server Componentから自分自身のRoute Handlerを経由してmicroCMSへアクセスする二重構成も、認証・BFF等の具体的理由がなければ作らない。

## 必要なリファレンスだけを読み込む

- **セットアップ**: `microcms-js-sdk`、環境変数、クライアント、型、安全な配置については [references/setup.md](references/setup.md) を読む。
- **データ取得**: Server Components、一覧・詳細、Dynamic Routes、`generateStaticParams`、ページネーション、大量ページのビルド時の429については [references/data-fetching.md](references/data-fetching.md) を読む。
- **キャッシュ・ISR**: Next.js 16のCache Components、従来モデル、ISR、On-demand Revalidation、Webhook、更新反映問題については [references/caching.md](references/caching.md) を読む。
- **プレビュー**: microCMSのDraft KeyとNext.js Draft Mode、プレビュー開始・終了Route Handlerについては [references/preview.md](references/preview.md) を読む。
- **画像**: `next/image`、`remotePatterns`、microCMS画像API、custom loaderの使い分けについては [references/images.md](references/images.md) を読む。

複数領域にまたがる場合は必要なリファレンスを組み合わせる。

例:

- 「Webhookで記事更新を即反映したい」 → `caching.md`
- 「下書きプレビューが古い」 → `preview.md` + `caching.md`
- 「画像転送量を減らしたい」 → `images.md` + `microcms-guide` の画像・performance原則

## 実装を変更するとき

既存プロジェクトでは次の順に進める。

1. 現在のmicroCMSクライアントとデータ取得関数を確認する。
2. キャッシュ戦略を確認する。
3. 問題を再現する経路を特定する。
4. 最小限の変更で解決する。
5. プロジェクト既存の命名・ディレクトリ・型・lint/format方針に従う。
6. 不要な依存パッケージや抽象化を追加しない。

ユーザーがコード修正を求めている場合は、説明だけで終わらせず、可能なら実際のファイルへ一貫した変更を行う。

## 更新が反映されない問題を診断する

「microCMSでは更新したのにNext.jsへ反映されない」場合は、次の順序で切り分ける。

1. microCMS Content APIを直接確認し、期待する公開データが返っているか。
2. Next.jsがどのデータ取得方式を使っているか。
3. `cacheComponents` の有無とキャッシュ設定。
4. 時間ベースのrevalidationかOn-demand Revalidationか。
5. Webhookが受信できているか。
6. `revalidatePath` / `revalidateTag` / `cacheTag` の対象が正しいか。
7. ホスティング・CDNなど別キャッシュ層があるか。

microCMSのCDNとNext.jsのキャッシュを混同しない。

## 品質基準

公式開発者ドキュメントの取得・仕様確認には、利用可能なら `microcms-docs` を併用する。設計判断や実装はこのSkillで進め、必要なページだけ確認する。未導入の場合は各referenceの公式出典を直接確認する。

- バージョン依存のNext.js挙動は、可能なら現在の公式Next.jsドキュメントを確認する。
- 新規コードも導入済みNext.js・SDKのバージョンに合わせる。最新ドキュメントのAPIを旧バージョンへそのまま持ち込まない。同梱内容と対象バージョンの公式仕様が矛盾する場合は公式仕様を優先する。
- キャッシュ戦略は更新要件から逆算する。
- 公開予約など時刻の正確性が重要な場合は、時間ベースISRだけ

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 6 — file references are metadata, not package contents.

View saved version →

---
name: microcms-wordpress-migration
description: WordPress から microCMS へコンテンツを移行するための手順書と品質チェック。構造の洗い出し、microCMS スキーマ設計、メディアのアップロードと URL 置換、リッチエディタ用 HTML 変換、案件ごとの移行スクリプト作成指針、件数・取りこぼし検証、リダイレクト表までを扱う。WordPress から microCMS への移行、WXR / WP REST API / ACF / カスタム投稿タイプ / Gutenberg / ショートコードを microCMS に持っていく話、WordPress コンテンツの一括登録・インポート、WordPress から microCMS への移行の見積もりや事前調査で使用する。フロントエンドの移行・実装は対象外。
---

# WordPress から microCMS への移行

WordPress から microCMS へコンテンツを移す。**案件ごとに移行スクリプトを書き、毎回同じ手順で検証する。** 全部を自動で変換することは目指さない。目指すのは次の 3 つ。

1. 移行できるもの・できないものを、書き込む前に人が判断できる形で出す
2. 同じ入力から同じ結果になるスクリプトにして、何度でも流し直せるようにする
3. 変換できなかったものを 1 件残らず記録して、人が直す作業リストにする

## 対象範囲

扱うのはコンテンツ・メディアの調査、スキーマ設計、変換・登録・検証と引き継ぎ資料の作成まで。WordPress のテーマ、テンプレート、CSS、画面機能の移植や新サイトの実装、リダイレクトの設定・本番切り替えは行わない。本文の意味を保つための HTML 変換と、旧 URL の対応表作成はデータ移行に含む。

フロントエンドの実装も求められた場合は別作業として扱い、Next.js なら `microcms-nextjs` を案内する（https://github.com/microcmsio/skills/tree/main/skills/microcms-nextjs）。未導入なら導入先を案内し、このスキルだけでフロントエンド実装を進めない。Next.js 以外を想定している場合は、フレームワークを勝手に変更しない。

## 読む順番

| いつ | 読むもの |
|---|---|
| 最初に必ず | `references/general.md`（全体の流れと、人が判断する場所） |
| 移行元を調査するとき | `references/wordpress.md`（取り出し方と構造の洗い出し） |
| スキーマを決めるとき・登録スクリプトを書くとき | `references/microcms.md`（フィールド対応表と API の制約） |
| スクリプトを作るとき | `references/scripting.md`（入出力・再実行・失敗記録・検証の実装指針） |
| `plan.md` を人に見せる前 | `references/plans.md`（料金プランの上限との照らし合わせと、超過時の費用） |
| 本文（HTML）を変換するとき | `references/richeditor.md`（入稿できる HTML と変換表） |
| 登録後・引き継ぎ前 | `references/validation.md`（品質チェックと報告書の形） |

## 移行スクリプトの作成

サンプルスクリプトは同梱しない。AI は棚卸しと承認済みの対応表に基づき、案件用のスクリプトを `migration/scripts/` に作る。作成時は `references/scripting.md` を読み、移行元固有の取り出しは `wordpress.md`、API 操作は `microcms.md`、本文変換は `richeditor.md` に従う。実行言語や依存パッケージは案件の環境に合わせて選ぶ。

件数が少ない移行なら、利用可能な microCMS の MCP ツールで直接登録してもよい。その場合も ID の付け方、登録の順番、対応表・失敗記録、登録後の検証は同じ手順で行う。

## 作業ディレクトリ

移行を始めたら、プロジェクト内に次の形で作る。

```
migration/
├── plan.md            # 洗い出し結果・構造の対応表・既定の扱い・先に決めてほしいこと（人が承認する）
├── input/             # 受け取ったファイル（WXR、wp-content/uploads を展開したもの）
├── raw/               # 移行元から取り出したそのままのデータ（書き出しの警告を含む）
├── transformed/       # microCMS の形に変換済みの JSON（登録スクリプトの入力）
├── media-map.json     # 旧 URL → 新 URL の対応表
├── media-skipped.json # 上げられなかったメディアと理由
├── logs/              # 変換時の警告、登録前の検査結果、登録結果
├── scripts/           # この案件用のスクリプト（案件ごとに作成）
├── redirects.csv      # 旧 URL → 新 URL のリダイレクト表
└── report.md          # 検証結果、人が直す作業リスト
```

## 接続情報

認証情報は、会話・ファイル・ログに一度でも書かれると取り消せない。

- **接続情報は `.env` など実行環境の秘密情報管理に設定する**（`.env` は `.gitignore` に入れる）。スクリプトは `MICROCMS_SERVICE_DOMAIN` と `MICROCMS_API_KEY` を環境変数から読み、値をコードに埋め込まない。実行環境に合う読み込み方法とコマンドを案件の `plan.md` に記録する。ローカルデータの変換や通信なしの検証に認証情報は不要。
- **値を表示しない。** 確認するときは「`MICROCMS_API_KEY`：設定済み／空／未設定」のように、名前と状態だけを報告する。`.env` を `cat` しない。
- **依頼文やチャットで値を渡されたら、** その値をファイルにもコマンドにも書き写さず、`.env` に入れ直してもらう。会話に残った値は無効にして発行し直すよう勧める。
- **`plan.md`、`report.md`、`logs/` に値を書かない。** 取り出した `raw/` の著者やコメントにはメールアドレスが入っている。移行に必要なものだけを残す。
- **WordPress の認証情報は受け取らない**（既定の受け取り方では要らない。`references/wordpress.md` の 0 章）。例外はサーバー上で WP-CLI を動かす場合だけで、SSH の接続は人にしてもらうか、移行用のアカウントを発行してもらい、終わったら無効にしてもらう。管理者のログインパスワードは受け取らない。
- **microCMS は移行用の API キーを別に発行してもらう。** 必要な権限だけを付け、終わったら削除してもらう。コンテンツ API は GET・PUT・PATCH・DELETE（POST は使わない）。Content API で全件集計する場合は、対象 API の「下書きコンテンツの全取得」「公開終了コンテンツの全取得」も付ける（`references/plans.md`）。マネジメント API はサービス情報・API・コンテンツメタ情報の取得、コンテンツの公開状態の変更、API の作成、メディアのアップロードと削除。公開状態変更の権限は、下書きからの公開と公開中から下書きへの切り替えに使う。

## 人の判断を必ず挟む場所

ここはエージェントが勝手に進めない。どれも取り消しにくいか、お金がかかるか、案件の事情でしか決まらない。

0. **事前確認** — 手元の WXR・uploads の調査に API キーや MCP 接続は不要。接続する段階で対象サービスを確認し、書き込み前に MCP の接続先も一致することを確かめる（`general.md` の 0）。MCP が別のサービスにつながっていることがあるので、一致を確かめるまで MCP で書き込まない。
1. **`plan.md` の承認** — スキーマと対応表を見せて、書き込みを始めてよいか確認する。プランなどの前提が後からわかった・変わったときは、設計を見直して承認を取り直す。
2. **API を作る直前** — 作る API とフィールドの最終版を見せる。API は作ったあとでマネジメント API では変更・削除できず（管理画面で人に直してもらうしかない）、間違えると作り直しになる。
3. **プランの上限と費用** — API 数、コンテンツ数、ファイルアップロードなどが契約中のプランに収まるかを、料金ページを取得して確かめ、`plan.md` に書く（`plans.md`）。超える場合は費用と代わりの案を並べ、人が選ぶまで API を作らない。同意なしに追加料金を許可しない。
4. **本番サービスへの書き

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 7 — file references are metadata, not package contents.