Experience Modernization Agent の推奨ガイド prompting-guide

移行は、7 段階のワークフローに従います。

1. エージェントがソースページをスクレイピングします。
2. セクション構造を識別します。
3. オーサリング分析を実行します。
4. コンテンツをブロックバリアントにマッピングします。
5. Markdown が生成されます。
6. これにより、読み込みインフラストラクチャが作成されます。
7. 結果のプレビューが表示されます。

エージェントは、次の 2 つのレベルの階層を使用してページを分析します。

• 最初に、セクションの境界（背景の変更、間隔の移動）を示します
• 次に、各セクション内のコンテンツのシーケンスを識別します。

オーサリング分析は、David's Model に従います。

• コンテンツシーケンスごとに、最初に「作成者は通常の入力でこれを作成できますか？」を確認します。
• デフォルトコンテンツ（見出し、段落、リスト、インライン画像）の方がブロックよりも優先されます。

エージェントは、新しいブロックを作成する前に、リポジトリのブロックライブラリから既存のブロックを再利用しようとします。

• コンテンツを既存のブロックにマッピングできない場合は、新しいブロックバリアントが作成されます。
• 変更のプロンプトを表示したり、新しいバリアントをリクエストしたり、インタラクティブにマッピングを調整したりできます。

ブロックバリアントはメタデータで追跡されます。

• 複数のページを移行する場合、エージェントは最初に既存のカスタムバリアントを読み込み、スタイルが一致すると再利用します（目的、カラー、タイポグラフィ、間隔、レイアウトに基づいて類似性のしきい値を 70% 設定します）。

ヘッダー、ナビゲーション、フッターは、ページの移行から除外されます。 これらは専用のスキルで処理されます。

各移行では、将来の一括読み込みに備えて読み込みインフラストラクチャ（ページテンプレート、ブロックパーサー、トランスフォーマー）が作成されます。

• これには、ページテンプレート（セクション構造）、トランスフォーマー（サイト全体の DOM クリーンアップ）、パーサー（ブロック固有のHTMLからテーブルへの変換）が含まれます。

• テンプレートは最初から推測されません。

• 1 回の実行でのテンプレートの混在はサポートされていません。

このプロンプトは、通常、ページ移行の最初の手順として自動的に呼び出されます。

CSS を使用して非表示になっているコンテンツも、DOM に存在する場合はキャプチャされます。

遅延読み込みされた画像とクライアントサイドでレンダリングされたコンテンツは、ヘッドレス Chromium でページをスクロールし、スクリプトを実行させることで処理されます。

WebP/AVIF/SVG画像は、互換性のために PNG に変換されます。

メタデータ（タイトル、説明、オープングラフタグ、JSON-LD 構造化データ、正規 URL など）が抽出されます。

DOM 内の画像は固定されています。

• background-image は img に変換されます。
• 画像要素が展開されます
• srcset は src に解決されます。
• 相対 URL は絶対 URL に変換されます
• へのインライン SVGは、img ファイルに変換されます。

サニタイズされたドキュメントパスが生成されます（小文字で .html 拡張子なし）。

次の出力が生成されます。

• screenshot.png
• cleaned.html （スクリプト/スタイルなし）
• metadata.json
• ローカルコピーを含む images/ フォルダー

ユーザーは、スクリーンショットのサイズを確認し、コンテンツ抽出用に特定のデバイスサイズ（モバイル、デスクトップ）を要求できます。

複数のブレークポイントでコンテンツを抽出すると、処理時間が長くなります。

設計の移行には次の 2 つの段階があります。

1. フェーズ 1 （サイト全体）では、以下を styles/styles.css に抽出します。

   • グローバルカラーパレットとアクセントカラー
   • タイポグラフィ システム （フォント、サイズ、太さ）
   • 間隔システム（パディング、余白、ギャップ）
   • セクションの背景（明、暗、色付き）
   • 基本コンポーネントスタイル（ボタン、リンク、画像）
   • 出力先

2. フェーズ 2 では、個々のブロックスタイルを移行し、/blocks/{name}/{name}.css でブロック固有の CSS を作成します。

ブロック スタイル設定（フェーズ 2）では、最初にサイト全体の設計（フェーズ 1）を完了する必要があります。

• グローバル設計システムは、参照をブロックする CSS カスタムプロパティを提供します。

推定時間：

• フェーズ 1: 5 ～ 10 分
• フェーズ 2:10～15 分

あいまいなリクエストは、デフォルトで移行を完了します（両方のフェーズ）。

ブロック批判は、移行されたブロックを元のソースと比較し、85% の視覚的類似性が達成されるまで、または 3 つのイテレーションが完了するまで、CSS 修正を繰り返し適用します。

スキルでは、最初にページ移行によってブロックが作成されている必要があります。

ブロック条件は、6 段階のワークフローに従います。

1. XPath セレクターを使用して、ソースページから元のブロックをキャプチャします。
2. これは批判的なセッションを初期化します。
3. 元のブロック（スクリーンショット、スタイル、HTML）を調べます。
4. 移行されたブロックが調べられます。
5. 要素を比較し、CSS 修正を含んだ類似性スコアを生成します。
6. 85% のターゲットに達するまで、修正を適用し、再検査します。

各イテレーションでは、すべての相違点を含む完全な批判レポートが表示され、すべての CSS 修正（視覚的な影響によって優先順位が付けられる）が適用され、プレビューで検証され、再検査されて改善指標が表示されます。

​ デザインのマイグレーション ​ が完了したら、ブロック基準を使用します。

ページ批判は、元のページと移行されたページをページ全体で視覚的に比較し、類似性が 85% のターゲットに達するか、3 回のイテレーションが完了するまで繰り返します。

ページ批判のワークフローは、次の 5 つのステップから成ります。

1. それは批判的なセッションを初期化します。
2. 元のページ上のすべての要素を調べます。
3. 移行されたページ上のすべての要素を調べます。
4. 優先順位の高い CSS 修正と類似性スコアを比較して生成します。
5. 85% のターゲットに達するまで、修正を適用し、再検査します。

ページ批判には、ソースページ URL と移行されたパス（例：「/about」）が入力として必要です。

ページ全体の忠実性を検証する場合や、複数のブロックを同時に検証する場合に、ページ批判を使用します。

特定のコンポーネントに的を絞った検証を行う場合は、​ ブロック条件を使用 ​ します。

次のワークフローをお勧めします。

1. ページを移行します。
2. デザインを適用します。
3. キーブロックに対するブロック批判の実行
4. 完全な検証を行う場合は、ページ批判を実行します。

このスキルでは、ページ全体または完全な Figma ファイルではなく、一度に 1 つのブロックが移行されます。

最適な結果を得るには：

• Figma で移行する特定のブロックを選択し、そのリンク（node-id）または名前をコピーします。
• 正確なブロックをターゲットにするには、URL に node-id パラメーターを指定します。

このスキルを実行すると、ホストされた環境で次の手順が自動的に実行されます。

1. ブロック構造の検出 - エージェントが Figma ノードを読み取り、レイヤーとコンポーネントを理解します。
2. グローバルスタイル抽出 - エージェントは、カラー、タイポグラフィ、スペースを CSS カスタムプロパティ（デザイントークン）として styles/styles.css に取り込みます。
3. ブロック固有のスタイルの作成 - エージェントは、移行されるブロックに固有の追加の CSS カスタムプロパティを作成します。
4. 既存のブロックへのマッピング - エージェントは、プロジェクトのブロックライブラリ内で最も近い一致ブロックを識別し、カスタムバリアントを作成します。
5. CSS 生成 - エージェントは、抽出された CSS カスタムプロパティを参照するスタイルを書き込み、デザインの一貫性を確保します。
6. アセットのダウンロード - エージェントは、Figma からホストされている環境のワークスペースに画像とアイコンを保存します。
7. Edge Delivery Services コンテンツ生成 - エージェントは、EDS ブロック構造に従ってマークダウンファイルを作成します
8. 出力検証 - エージェントは結果をプレビューし、元の Figma デザインと視覚的に比較します。

スキルは、まずメタデータを読み（手順 1）、構造を理解してから、詳細なデザインコンテキストを抽出します（手順 2～5）。

• この段階的アプローチにより、大きな Figma ファイルや複雑な Figma ファイルに関する問題を回避できます。

このスキルは、スタイルファーストのアプローチを採用しています。

• すべてのスタイルは、CSS が書き込まれる前に、CSS カスタムプロパティ（デザイントークン）として抽出されます。
• これにより、移行されたブロックが設計システムとの一貫性を維持します。

プロンプトには、Figma URL （fileKey およびオプションの node-id）または Figma ファイルキーが入力として直接必要です。

Edge Delivery Servicesナビゲーションは、（header.js によって実施される） 3 つのセクション構造を適用します。

1. ブランド （セクション 1）：ロゴとプライマリーブランディングリンク
2. セクション （セクション 2）：オプションのドロップダウンを含むメインナビゲーションメニュー
3. ツール （セクション 3）：ユーティリティリンク（購入、ログイン、買い物かご）

ナビゲーションコンテンツは、ルートディレクトリの nav.md に格納されます。

セクションは（---）マーカーで区切られます。

ネストされたリストを含む太字の項目（**Text**）は、ドロップダウンを作成します。

ナビゲーション内のリンクは、ドキュメントオーサリングの自動ラッピング動作により、ボタンとしてレンダリングされる場合があります。

• ヘッダーブロックには、ボタンクラスをナビゲーションリンクから削除するコードが含まれています。

このエージェントは、すべてのEdge Delivery Services開発に必須のプロセスである CDD （Content-Driven Development）に従います。

• コードを記述する前に、コンテンツモデルについて尋ね、コンテンツをテストします。

CDD の哲学では、開発者のニーズよりも作成者のニーズの方が重要です。

• コンテンツモデルは、作成者が直感的に使用する必要があります（より複雑な装飾コードを意味する場合でも）。

テストコンテンツを最初に作成すると、次の機能が提供されます。

• 即時テスト機能
• PSI チェック用の PR 検証リンク
• 作成者向けライブドキュメント
• コードファーストのアプローチが失敗するエッジケースの発見

エージェントは、実装前に、Block Collection および Block Party 内の類似ブロックを検索し、パターンと再利用可能なコードを見つけます。

CSS のみの簡単な調整の場合にのみ CDD をスキップします（ただし、検証用にテストコンテンツは特定できます）。

Edge Delivery Servicesには、次の 4 つの正規モデルタイプがあります。

• スタンドアロン： ユニークなビジュアル要素またはナレーション要素（ヒーロー、引用ブロック）
  • ブロックコンテンツを含む単一のテーブル
• コレクション： 半構造化コンテンツ（カード、カルーセル）の繰り返し
  • 繰り返し行のパターンを含むテーブル
• 設定： 設定コントロールが表示される API 駆動型コンテンツまたは動的コンテンツ（ブログリスト、検索結果）
  • キー値の設定行を含むテーブル。
• 自動ブロック： 作成者がセクション/デフォルトコンテンツとして作成し、変換される複雑な構造（タブ、YouTubeの埋め込み）

1 行につき使用できるセルの数は 4 個までです。

• 関連要素をセルにグループ化します。

スタイルの違いに関しては、設定セルよりもブロックのバリアントを優先します。

​ ポステルの法則に従う ​：入力構造に関して柔軟であること。

• ヒーローブロックは、コンテンツが 1 つのセルにあるか、2 つのセルに分割されているか、別々の行にあるかを問わず機能する必要があります。

このスキルは、通常、ブロック作成時にコンテンツ駆動開発によって自動的に呼び出されます。

​ ブロックコレクション ​ はAdobeで維持管理され、ベストプラクティス、優れたコンテンツモデリング、高パフォーマンス、アクセシビリティが検証されています。

• 一般的に必要なブロックに制限されています。 ここから開始。

Block Party はコミュニティ主導であり、実験的なアプローチを含む幅広い多様性を提供します。

• また、サイドキックプラグイン、ビルドツール（webpack、vite、sass）、統合も含まれます。
• ブロックコレクションに必要なものが含まれていない場合は、を使用します。

検索時に代替名を考える

• FAQ = アコーディオン
• ギャラリー= カルーセル/スライドショー
• ナビゲーション = メニュー/ヘッダー

ブロックパーティは、承認済/キュレートされたエントリのみを返します。

テストは、「価値とコスト」の理念に従い、価値がコストを超えた場合にテストを作成し維持します。

• Keeper テスト （単体テスト）は、ロジックが重いユーティリティ、データ処理、API 統合用です。 これらは高速で、管理が容易で、再利用されたコードでリグレッションをキャッチします。
• スローウェイテスト （ブラウザーテスト）は、DOM 変換と視覚的検証のためのものです。 を使用して実装を検証し、PR レビュー用のスクリーンショットを取得してから、破棄します。

使い捨てのテストは test/tmp/ で行われ、コンテンツは drafts/tmp/ でテストされます（両方とも考慮されます）。

PR を開く前に、次のことを確認します。

• 既存のテストは合格
• 単体テストは、新しいロジック用に作成されます
• ブラウザーの検証が完了しました
• すべてのバリアントがテストされます
• レスポンシブ動作の検証
• リンティングパス

よくある問題には、既知のパターンがあります。

• 「about:error」を示す画像：通常、ブロック JS で createOptimizedPicture 呼び出しが見つからないか、DOM 再構築の前に呼び出される
• ブロックがレンダリングされない: Markdown でブロック名形式を確認し、ブロックに .js と .css の両方のファイルが blocks/ にあることを確認します。
• CSS が読み込まれない：ファイルパスを確認し、CSS ファイルが存在することを確認し、ブラウザーの「ネットワーク」タブを確認します。
• 変更が表示されない：コード同期には 3～5 秒かかります。 ハード更新を試してください（Ctrl+Shift+R）。

エージェントは、各レイヤーを体系的にチェックします。

1. Source ファイル
2. レンダリングされた出力
3. ブロックコード
4. ブラウザーコンソール

エージェントは、http://localhost:3000 でローカルプレビューを確認できます。