wp-playground-development

WordPress Playground 開発スキル

概要

WordPress Playground ベースのデモと再現可能な環境を体系的にレビューするためのガイダンスです。基本原則： Playground のセットアップは、Blueprint または CLI のエントリーポイントだけからでも、決定論的で、移植可能で、理解しやすいものにする必要があります。レビューでは、Blueprint の構造、ローカル CLI の使用方法、埋め込みデモ、再現環境、デモ固有の WordPress 設定を確認します。

使用する場面

次の場合に使用します：

• Blueprint JSON ファイルをレビューする場合
• Playground を埋め込んだり、リンクしたりするドキュメントを監査する場合
• セットアップ不要のバグ再現環境やデモを作成する場合
• ローカルのワークフローやテストにおける Playground CLI の使用方法をレビューする場合
• ブロック、プラグイン、テーマ向けの再現可能な環境を設計する場合

次の場合には使用しないでください：

• Playground を使わない一般的なブロックやプラグインのレビュー
• Playground のコンテキスト外での WP-CLI 操作
• 静的解析や CI の設定のみを行う場合

コードレビューワークフロー

1. Playground のエントリーポイントを特定する

   • Blueprint JSON
   • Playground CLI コマンド
   • 埋め込み iframe または Blueprint URL
   • 問題を再現するために使用するローカルドキュメントやスクリプト

2. まず再現性を確認する

   • 必要に応じて WordPress と PHP のバージョンを明示する
   • 手順を順番に並べ、自己完結させる
   • Blueprint やドキュメントに記載されていない隠れた手動手順がない

3. セットアップ手順をレビューする

   • テーマやプラグインのインストールと有効化
   • ログイン、サイトオプション、コンテンツの投入
   • ファイルの書き込み、コピー、マウント
   • Blueprint 内で使用する wp-cli の手順

4. 開発者の使いやすさをレビューする

   • 試行錯誤せずに再実行できるか
   • ランディングページに意味があるか
   • ローカルとブラウザベースのフローが明確に分けられているか

5. 指摘事項を分類する

   • CRITICAL： 再現できないセットアップ、隠れた依存関係、誤った手順の順序、ドキュメントに記載されていない外部要件
   • WARNING： バージョンが暗黙的、壊れやすいマウント、分かりにくいランディングページ、小さな問題に対して過剰に複雑な再現環境
   • INFO： 手順を簡略化できる、デモとテストデータを分離できる、より明確な Blueprint パターンを使える

ファイル種別ごとの確認事項

Blueprint ファイル

• CRITICAL：Blueprint を機能しなくする必須のセットアップ手順が欠けている
• WARNING：バージョン互換性が重要なのに、preferredVersions が明示されていない
• WARNING：Blueprint と同じ場所にあるファイルに再現環境が依存しているが、その説明がない
• INFO：より明確な landingPage を設定できる

Playground CLI のワークフロー

• WARNING：ローカルワークフローで server または start を使用しているが、マウントの説明がない
• WARNING：Blueprint のパスや自動マウントに関する前提が暗黙的
• INFO：より決定論的なフローにするため、run-blueprint または build-snapshot を使用できる

埋め込みデモと再現環境

• CRITICAL：デモが Blueprint に記録されていない手動の管理者セットアップに依存している
• WARNING：埋め込み例が、実証する問題に対して大きすぎる、または汎用的すぎる
• INFO：学習用／デモ用コンテンツとバグ再現用コンテンツを分離できる

すばやく検出するための検索パターン（PG-21）

次の rg コマンドを使用して、Playground 関連のファイルやセットアップロジックを検索します。

Playground の検出

rg -n "playground|blueprint|@wp-playground" . -g '*.{md,json,js,ts,tsx,yml,yaml}'
rg -n "\"steps\"|\"landingPage\"|\"preferredVersions\"" . -g '*.json'

CLI と埋め込みのフロー

rg -n "run-blueprint|build-snapshot|@wp-playground/cli|npx @wp-playground/cli" . -g '*.{md,js,ts,sh,yml,yaml}'
rg -n "blueprint-url|playground.wordpress.net|wordpress.org/playground" . -g '*.{md,html,js,ts}'

再現手順

rg -n "\"step\": \"(login|wp-cli|installPlugin|installTheme|writeFile|mkdir|cp|mv|enableMultisite)\"" . -g '*.json'

参考ファイル

• references/blueprint-patterns.md - Blueprint の構造、手順の選択、決定論的なセットアップ
• references/cli-and-local-workflows.md - @wp-playground/cli、マウント、ローカルワークフロー、スナップショットの使用方法
• references/embedding-and-repros.md - 埋め込みデモ、Blueprint URL、問題の再現パターン
• references/sample-playground-blueprint.json - ローカルテストや応用に使える、最小限の再現可能な Blueprint フィクスチャ

出力形式（PG-23）

指摘事項ごとに、次の内容を記載します。

1. 重大度：CRITICAL、WARNING、INFO のいずれか
2. ファイルと行番号
3. 再現環境またはデモに関する問題の概要
4. Playground の信頼性や明確さにとって重要な理由
5. 推奨する修正方法

問題が見つからなかった場合は、その旨を明確に記載し、バージョンのずれ、再現手順の不足、壊れやすいローカルマウントなど、残る曖昧さにも触れてください。