datocms-cma

DatoCMS コンテンツ管理 API スキル

CMA の操作とスクリプトには、このワークフローを使用します。アドバイスやコードの説明の場合は、実行とセットアップを省略してください。「公開して」などの短い追加指示では、先行する DatoCMS のタスク、選択したルート、プロジェクト、環境、対象範囲が引き継がれます。

1. セットアップの前に実行方法を選択する

廃止された MCP のリクエスト：実行しません。 ユーザーが廃止済み／レガシー MCP をリクエストした場合、または以前のローカル連携が動作しなくなったと報告した場合は、次のように返信します：「その連携は廃止されました。現在の DatoCMS MCP セットアップを使用してください。」最終回答にもそのリンクを含めてください。レガシーまたは現在の DatoCMS ツールを呼び出さずに、そのタスクを終了します。現在利用できる接続があっても、別の方法に置き換える許可にはなりません。廃止された連携の調査、修復、再インストール、再設定は行わないでください。ユーザーが CLI または現在の MCP を求めている場合を除き、以下の通常の方法選択ルールより先に、この停止条件を適用します。接続／認証エラーだけでは、連携が廃止されたとは判断できません。

MCP が接続されていても、使用可能なら CLI がデフォルトです。 例外は、ユーザーがツールを明示的に選択した場合、またはこの会話ですでに使用した方法がある場合のみです。接続がインストール済み、または認証済みであることは、その利用可能性を示すものであり、ワークフローが確立されていることを意味しません。

タスクに関連する、公開済みの機能だけを確認します。利用可能とは、今すぐ使えることを指し、インストール可能というだけでは該当しません。起動時の接続確認を実行したり、MCP クライアントの設定をスキャンしたりしないでください。

• 明示された方法： CLI が使用可能であっても、現在の MCP または CLI のいずれかをユーザーが選んだ場合は、その選択に従います。後続のリクエストでは、ユーザーが変更を求めない限り、確立済みの方法を維持します。
• 方法の固定： いったん選択したライブ操作の方法は、以降の別トピックのリクエストも含め、ユーザーが明示的に切り替えるまで会話全体で維持します。MCP を選択した場合 → ライブ作業では datocms-cli を読み込んだり、CLI コマンドを実行したりしません。スキーマの参照も含みます。CLI を選択した場合 → references/mcp.md を読み込んだり、DatoCMS MCP ツールを呼び出したりしません。以下のローカル成果物は、それぞれのワークフローを維持します。
• 希望または確立済みの方法がない場合： CLI と現在の MCP の両方が使用可能なら、CLI を選択します。MCP が接続されているだけでは、MCP を使うリクエストにはなりません。現在の MCP だけが使用可能なら、パッケージのインストール、CLI へのログイン、プロジェクトのリンクは行わずに MCP を選択します。CLI だけが使用可能なら、CLI を選択します。
• どちらも準備できていない場合： この環境で不足している前提条件を説明します。ローカル CLI 作業には CLI のセットアップが必要な場合があります。ローカルで実行できないクライアントによるライブ操作には、サポート対象のプロジェクト接続が必要です。MCP は任意であり、すべてのスキルに必要な前提条件ではありません。
• ローカル成果物： マイグレーション、リポジトリ設定、アプリケーションコードは、ローカル開発のワークフローを維持します。リモート実行で、バージョン管理されたマイグレーションの代わりにしたり、要求されたローカル成果物を作成したりすることはできません。アプリ／サーバーのコードまたは無人実行の CMA コードでは、既存のクライアント設定と生成済みの型を確認して再利用します。セットアップは、不足しており、かつ必要な場合にのみ追加します。

方法を選択した後：

方法または成果物	必要に応じて読み込むもの
CLI の単発呼び出しまたはエンドポイントのドキュメント	../datocms-cli/references/direct-cma-calls.md。
CLI のループ、ページネーション、依存する呼び出し、またはローカライズされたコンテンツ／ブロック／Structured Text の編集	標準入力／ファイルモードとランタイムグローバルのために ../datocms-cli/references/cma-script.md。
現在の MCP	references/mcp.md。公開されているツールが、現在のランタイム契約を提供します。
選択した CLI 作業に不足している前提条件	datocms-cli のセットアップワークフロー。リンクする前に、必ず対象プロジェクトを確認します。候補が 1 つだけと推測できても、同意を得たことにはなりません。
コードが独自のクライアントを構築する場合（アプリ／サーバー、CI、cron、共有の無人実行スクリプト）	パッケージの選択、トークン／環境変数の設定、エラー処理について references/client-setup-and-errors.md。

メソッドのシグネチャ、ペイロード、認証、プロジェクト／環境の選択、実行要件については、選択したツールの最新のドキュメントを使用します。共通リファレンスにある CLI ドキュメントのヒントは、CLI 作業にのみ適用されます。MCP タスクで、リンク先のリファレンスを通じて CLI を前提条件にしてはいけません。

2. 対象範囲とスキーマの進め方を決める

既知のプロジェクトと環境を再利用します。不足している情報だけを確認し、対象や依頼された操作が曖昧な場合は質問します。別のツールを選んでも、追加の操作、異なる環境、公開が許可されるわけではありません。スキーマの変更にはスキーマ編集権限（can_edit_schema）が必要です。実行前に、プライマリ環境に対する直接的なスキーマ変更について明示的に確認してください。

スキーマに依存する変更を行う前に、関連するモデル、フィールド、バリデーター、現在のレコード値を確認します。CLI モードでは、../datocms-cli/references/schema-inspect.md にある対象を絞った schema:inspect のガイダンスを使用します。MCP モードでは、公開されているスキーマツールを使用します。範囲の狭い編集のために、プロジェクト全体を取得しないでください。

タスク	進め方
破壊的なスキーマ変更：フィールドやモデルの削除、データ損失を伴うフィールド型の変更、bulk_destroy によるレコード操作	まずフォークしたサンドボックスに対して、datocms-cli のマイグレーションを行います。明示的かつ繰り返し確認を得ずに、プライマリ環境に対して実行してはいけません。
可逆的なスキーマ変更：フィールドやモデルの追加・名前変更、バリデーターの変更、フィールドセットの並べ替え	すでに決まっていない場合は、レビュー可能なマイグレーションとサンドボックスへの直接変更のどちらを希望するか、ユーザーに確認します。リポジトリでマイグレーションを使用している場合や、作業がセカンダリブランチで行われている場合は、マイグレーションを優先します。迅速なサンドボックスでの反復作業には、直接変更も適切です。
明示的な単発操作、またはマイグレーションを使用しない指定	変更が破壊的でない限り、直接変更に従います。マイグレーションを繰り返し提案しないでください。
コンテンツ操作：公開・非公開、個別レコードの削除、フィールド編集、一括値更新、アップロードのメタデータ	選択した方法を使用します。マイグレーションは不要です。許可されたレコード、フィールド、ロケール、公開状態を維持します。
環境間でバージョン管理して再適用できる形で依頼された変更	datocms-cli のマイグレーションガイダンスとローカルの成果物を使用します。

利用可能な場合は、関連するガイダンスを自分で読み込んでください。ユーザーにスキル間を行き来させないでください。ローカルの成果物をここで作成できない場合は、リモートでの変更に黙って置き換えるのではなく、ローカルで利用できない機能について説明してください。

3. 関連するワークフローのみを読み込む

メソッドのドキュメントには API の形式が記載されています。これらのリファレンスには DatoCMS の編集ワークフローと注意点が記載されています。作成中の操作について、現在のメソッドの詳細のみを参照してください。選択したツールが関連するガイダンスをすでに返している場合は、重複して読み込まず、その内容を再利用してください。すべてのリファレンスを事前に読み込んだり、変更されていないリファレンスを後続のやり取りで再読したりしないでください。

タスク	リファレンス
レコードのライフサイクル、公開、参照	references/records.md
アップロードとアセットのメタデータ	references/uploads.md
スキーマの直接変更	references/schema.md
フィルタリング（作成者の監査を含む）、クエリ、コレクションのページネーション	references/filtering-and-pagination.md。インストール済み SDK が広範なオブジェクトを受け付ける場合でも、ここでフィルター演算子を確認してください。
ローカライズされたフィールドとロケールのバックフィル	references/localization.md。ロケールの追加やバックフィルを行う場合は、references/editing-records.md も参照してください。
Modular Content、Single Block、ブロックの走査	references/editing-records.md
Structured Text のレコード作成・更新・バックフィル	CMA への適応については references/editing-records.md、DAST の操作については ../datocms-structured-text/references/document-model.md と、その編集または変換に関するリファレンスを参照してください。
環境の操作	references/environments.md
ロール、トークン、コラボレーター	references/access-control.md
要求された移行スクリプト	references/migration-patterns.md と datocms-cli の移行ガイダンス
ローカルで生成された CMA 型	references/type-generation.md
Raw メソッド、高度なクライアントの動作、プラットフォームの制限	references/client-types-and-behaviors.md
プロジェクト設定、メンテナンスモード、サブスクリプションの制限、使用状況	references/project-settings-and-usage.md
Webhook／ビルドトリガー、スケジュール／ワークフロー、メニュー、プラグイン、保存済みフィルター、アップロードのトラック／タグ、監査ログ	references/resource-gotchas.md の該当セクション

タスクが複数の主題にまたがる場合にのみ、リファレンスを組み合わせてください。たとえば、ローカライズされた Structured Text の編集には、ローカライズと編集に関するガイダンスが必要です。コンテンツ操作でスクリプトを使用するというだけの理由で、移行や型生成のガイダンスを読み込まないでください。

4. 操作を実行する

• 選択したランタイムの認証済みクライアント、利用可能なヘルパー、スクリプト形式を使用してください。CLI のグローバル変数、インポート、ファイルモードの規約を別のランタイムに流用しないでください。クライアントの構築時は、認証情報をチャットやハードコードされた文字列ではなく、環境変数から読み込んでください。必要最小限の権限を使用し、該当する場合はサンドボックスを明示的に指定してください。
• 簡易 API を優先してください。JSON:API ペイロードやリレーションシップのメタデータが必要な場合に限り、生のメソッドを使用してください。利用可能な場合、コレクション全体を走査するには listPagedIterator() を for await...of とともに使用してください。nested: true を指定した items では、perPage を 30 以下（デフォルト）にしてください。API はそれより大きいページを拒否します。イテレーターが値を引き下げることはありません。ネストされたレコードでは、独自のフィールドはフラット化されます（record.title）。埋め込みブロックのフィールドは引き続き block.attributes の下にあります。
• ローカライズされたコンテンツ、ブロック、Structured Text を編集する場合は、現在のレコードを読み込んでから変換するスクリプトを 1 つ使用してください（CLI モードでは cma:script）。必要に応じてネストされたブロックを取得し、型付きブロックヘルパーを使用してください。無関係なフィールド、ロケール、ブロック、リンク、アップロードのメタデータを保持し、部分的な読み込み結果からレコード全体を再構築することは避けてください。
• Structured Text では、編集リファレンスに従い、テキストのラウンドトリップ、型付きノード／ブロックの変更、ルートへの追加の順で行ってください。置き換えを求められていない限り、既存のブロック ID と参照を保持してください。
• レコードの呼び出しとヘルパーでは、正確なプロジェクト型を使用してください。型推論と型ガードを優先し、不一致を隠すために any、unknown、キャストを使用しないでください。提供されているプロジェクト型にローカルでの生成手順は必要ありません。型生成のガイダンスに従うのは、独自の型モジュールを必要とするローカルコードに限ります。
• 選択したランタイムの機能を使用して、操作の境界で API エラーを処理してください。公開されている場合は ApiError と TimeoutError も含めます。認証および権限の失敗は正確に報告し、別の経路で回避しないでください。タイムアウトや書き込み応答の欠落がある場合、結果が不確かなため、再試行する前に状態を確認してください。また、その書き込みを別の経路やツールから再実行してはいけません。
• 長時間実行されるスクリプトでは、選択したランタイムの出力機能を使用して、進捗と最終的な合計を報告してください。

5. 検証して報告する

同じプロジェクト、環境、認可された範囲を対象に検証してください。保存されたフィールド／ノードの値を、元の読み込み結果の独立したスナップショットと比較し、オブジェクトにはディープイコールを使用してください。オブジェクトの同一性やシリアライズされた更新ペイロードでは、保持されたことを確認できません。ネストされた読み込みでは、ブロック ID と部分更新が完全なオブジェクトに展開されます。依頼された変更、無関係なコンテンツ、ロケール、リンク、公開状態を確認してください。公開には別途認可が必要です。スクリプトの型、ヘルパー、ページネーション、エラー処理が選択したランタイムの契約に沿っていることを検証してください。

実際に実行および検証した内容を報告し、部分的な結果や不確かな結果も明記してください。ローカルコードの成果物では、検証とライブ実行を区別してください。ローカルの CLI 設定の不足が関係するのは、その成果物または選択した経路で CLI が必要な場合に限られます。

その他のタスク

CLI の設定、マイグレーション、スキーマ生成、CLI 環境のワークフロー、オンボーディング時のインポート、プラグイン管理、複数プロジェクトの同期、CI/CD には datocms-cli を使用してください。ユーザーがセットアップの計画や手順の説明を求める場合（マイグレーションとリリース、複数プロジェクトの同期、プロジェクトへのインポート、Webhook／ビルドトリガー）には datocms-setup を使用してください。DAST の純粋な構築、検査、編集、変換には、プロジェクトのセットアップに先立って datocms-structured-text を使用してください。CMA 操作でドキュメントを永続化する場合は、このスキルと組み合わせてください（通常のレコード操作では必要ありません）。GraphQL によるコンテンツの読み取りには datocms-cda、フレームワークのコードには datocms-frontend-integrations、プラグインの開発には datocms-plugin、実装を伴わないモデリングの判断には datocms-content-modeling を使用してください。

兄弟リファレンスが見つからない場合は、datocms/agent-skills からそのスキルをインストールするか、バンドル全体を更新してください。