---
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呼び出し、画像URL、キャッシュ処理を確認する。
3. 問題を解決できる最小限かつ一貫性のある変更を行う。
4. プロジェクトで既に使われている言語、モジュール方式、命名、フォーマット、依存関係の方針に従う。
5. microCMSではなく、ホスティング環境やアプリケーションフレームワークに依存する挙動は明示する。

既存実装だけで適切に解決できる場合は、新しい依存パッケージを追加しない。

## 広範なmicroCMSの依頼に対応する

「microCMSを使ってサイトを作りたい」のような広範な依頼では、以下の順序で進める。

1. サイト・アプリケーションの種類と、管理対象のコンテンツを特定する。
2. API・コンテンツモデルを高い粒度で提案する。
3. 使用するクライアントやフレームワークを確認する。
4. 適切なmicroCMS連携方法を提案する。
5. 詳細なフレームワーク実装は、利用可能であれば対応する専門Skillに委ねる。
6. プレビュー、コンテンツ更新、キャッシュ、画像、Webhookなどの重要事項は、そのプロジェクトに関連するものだけを提示する。

最初からmicroCMSのすべての機能を説明して、ユーザーを圧倒しない。

## 品質基準

- 実装方法を求められた場合は、そのまま利用しやすいコード例を提示する。
- 意味のあるトレードオフが存在する場合は、その推奨理由を説明する。
- microCMSで確認されている挙動と、一般的なWeb開発上のアドバイスを区別する。
- 同梱リファレンスで確認できる、現在サポートされているAPI・SDKの利用方法を優先する。
- 小さな実装例では不要な抽象化を避ける。
- シークレット、プレビュー、キャッシュ、画像配信では、本番環境で安全に利用できるデフォルトを優先する。