payloadcms

payloadcms — Payload CMS オペレーター

キーワード：payload、payloadcms、headless cms、payload config

このスキルを使用する場面

• 新しい Payload プロジェクトをセットアップする（または既存の Next.js アプリに Payload を追加する）
• コレクション、グローバル、アクセス制御、フィールドスキーマを定義または更新する
• Payload をローカルで実行・開発・テストし、管理画面と API の動作を確認する
• 安全なコンテンツモデルのマイグレーションとロールバック戦略を計画する
• 明示的な検証チェックを含め、本番環境に対応した Payload の変更を準備する

このスキルを使用しない場面

• Payload のランタイムコンテキストを伴わない一般的な API 契約の作業 → api-design を使用する
• Payload 固有のセットアップ以外の認証アーキテクチャに関する決定 → authentication-setup を使用する
• Payload のモデル制約を伴わない、データベースの物理スキーマのみの調整 → database-schema-design を使用する
• Payload のランタイムに特化しない、広範なデプロイオーケストレーション → deployment-automation を使用する

手順

ステップ 1）作業モードを特定する

編集を始める前に、主となるモードを 1 つ選びます。

モード	使用する場面	主な成果物
ブートストラップ	新規インストールまたは初回統合	ローカルで動作する Payload アプリ
モデリング	コレクション／グローバルスキーマの更新	レビュー済みモデル差分とマイグレーションのメモ
ランタイムデバッグ	管理画面／API の障害または設定ミス	根本原因と検証済みの修正
リリース準備	本番環境へのロールアウト依頼	リスク／ロールバックと検証チェックリスト

ステップ 2）事前チェック

1. リポジトリ内のランタイム／ツールチェーン（node、パッケージマネージャー、フレームワークの構成）を確認する
2. Payload の設定（payload.config.*）とモデルファイルを探す
3. 環境変数／シークレットの構成（DATABASE_URI、ストレージ／認証キー）を確認する
4. スキーマを編集する前に、既存のマイグレーション履歴を調べる

ステップ 3）有効な最小限のワークフローを実行する

A. ブートストラップ

• リポジトリのパッケージマネージャーに従って依存関係をインストールする
• 必要最小限のコレクションを含む Payload 設定を生成／初期化する
• ローカル開発環境を起動し、次の両方を確認する：
  • 管理 UI が読み込まれる
  • 少なくとも 1 つのコレクションに対して API が応答する

B. モデリング

• 一度に 1 つの範囲に限定したモデル変更（フィールドの追加／削除／型変更）を行う
• 影響範囲を記録する：対象コレクション、API 出力、管理フォーム、シード／インポートジョブ
• マージ前にマイグレーションとロールバックの手順を準備する

C. ランタイムデバッグ

• 具体的な失敗エンドポイント／ページを使って、ローカルまたはステージング環境で再現する
• 設定、環境変数のバインディング、アクセスルール、アダプターの接続設定を確認する
• 明確な修正前／修正後の証拠（エンドポイントと管理画面の動作）で修正を検証する

D. リリース準備

• マイグレーションの順序とダウンタイムに関する前提を確認する
• ロールバックのメモを追加する（マイグレーションの取り消し、バックアップの復元、使用している場合はフィーチャーフラグの無効化）
• 検証リストが CI またはステージングのスモークテストで実行できることを確認する

ステップ 4）検証チェックリスト

• Payload サーバーがスキーマ／ランタイムエラーなしで起動する
• 変更したコレクション／グローバルを少なくとも 1 つ、API と管理画面の両方で検証する
• マイグレーション手順が決定的で、元に戻せる
• 本番環境向けの変更には、リスクとロールバックのメモがある

例

例 1：新しいコレクションを安全に追加する

Prompt: "Add a blog-post collection to our Payload app and keep migration risk low"

Mode:
- Modeling

Expected flow:
- Locate payload config and collection directory
- Add collection schema with access defaults
- Run local checks (admin + API)
- Document migration/rollback in PR notes

例 2：壊れた管理パネルのルートをデバッグする

Prompt: "Payload admin page fails after yesterday's schema change"

Mode:
- Runtime debug

Expected flow:
- Reproduce failure
- Isolate misconfigured field/access/env issue
- Apply minimal fix
- Verify admin loads and affected API endpoint works

ベストプラクティス

1. モデル変更は PR ごとに小さく、監査可能な範囲に保つ
2. マイグレーションとロールバックのメモがないスキーマ変更は、決してマージしない
3. 変更対象のモデルについて、管理 UI と API の両方を検証する
4. 暗黙のデフォルトより、明示的なアクセスルールを優先する
5. 環境変数のバインディングとアダプター設定を、最優先で確認する

参考資料

• Payload リポジトリ：https://github.com/payloadcms/payload
• Payload ドキュメント：https://payloadcms.com/docs/getting-started/what-is-payload
• 調査エビデンスの実行結果：.survey/hourly-skill-candidates-20260427-095216/evidence.json