評価拡張機能のチュートリアル

Cursor > Settings > Cursor Settings > Tools & MCP​に移動し、commerce-extensibility ツールセットがエラーなしで有効になっていることを確認します。 エラーが表示された場合は、ツールセットのオンとオフを切り替えます。

{width="600" modal="regular"}

カーソルのコンテキストで任意のドキュメントを無効にします。

• Cursor > Settings > Cursor Settings > Indexing & Docs​に移動し、一覧されているドキュメントをすべて削除します。

{width="600" modal="regular"}

商品レーティング拡張機能のコードを生成：

• カーソル チャット ウィンドウから、Agent モードを選択します。
• 次のプロンプトを入力します。

Implement an Adobe Commerce as a Cloud Service extension to handle Product Ratings.

Implement a REST API to handle GET ratings requests.

GET requests will have to support the following query parameters:

sku -> product SKU

担当者の質問に正確に答えて、最適なコードを生成できます。

拡張機能プロンプトが入力されたエージェント モードの {width="600" modal="regular"}

拡張機能の要件について明確な質問を求める {width="600" modal="regular"}

次のサンプルテキストを使用して、エージェントの質問に答え、ランダムな評価データを設定します。

Yes, this headless extension is for Adobe Commerce as a Cloud Service storefront,
but we do not need any authentication for the GET API because guest users should be able to use it on the storefront.

This extension is called directly from the storefront, no async invocation, such as events or webhooks, is required.

Start with just the GET API for now, we will implement other CRUD operations at a later time.

We do not need a DB or storage mechanism right now, just return random ratings data between 1 and 5 and a ratings count between 1 and 1000.

The API should only return the average rating for the product and the total number of ratings.
We do not need to add tests right now.

エージェントは、実装の信頼できる唯一の情報源として機能するrequirements.md ファイルを作成します。

実装の詳細を含むAI エージェントによって作成された {width="600" modal="regular"}

requirements.md ファイルを確認し、計画を確認します。

すべてが正しく見える場合は、エージェントに対して​ フェーズ 2 - アーキテクチャ計画 ​に移動するよう指示します。

アーキテクチャ計画の見直し：

エージェントにコード生成を続行するように指示します。

エージェントは必要なコードを生成し、次の手順を詳しく説明します。

{width="600" modal="regular"}

{width="600" modal="regular"}

{width="600" modal="regular"}

担当者に、コードをローカルでテストする方法を尋ねます。

Test the ratings API locally on a dev server using cURL.

エージェントの指示に従い、APIがローカルで動作していることを確認します。

ローカル API テスト用の {width="600" modal="regular"}

{width="600" modal="regular"}

生成されたコードを確認したら、次のプロンプトを使用して拡張機能をデプロイします。

Deploy the ratings API.

エージェントは、デプロイ前にデプロイ準備評価を実行します。

{width="600" modal="regular"}

評価結果に確信がある場合は、展開を続行するようにエージェントに指示します。

エージェントはMCP ツールキットを使用して、検証、ビルド、デプロイを自動的に行います。

{width="600" modal="regular"}

storefront フォルダーに移動します。

cd storefront

新しいカーソルウィンドウでストアフロントフォルダーを開きます。

または、Cursor CLIがインストールされている場合は、ターミナルで次のコマンドを使用してウィンドウを開きます。

cursor .

ローカル開発サーバーを起動します。

npm run start

ブラウザーで、製品ページに移動します。

http://localhost:3000/products/llama-plush-shortie/adb336

定型文のストアフロント製品詳細ページ（PDP）を確認し、視覚的な製品評価がないことに注意してください。

エージェントで次のプロンプトを使用します。

Integrate the ratings API into the PDP to show star ratings and a review count for products. Here's the service contract: @RATINGS_API_CONTRACT.md

担当者は、タスクの複雑さを評価し、段階的なワークフローを呼び出します。 フェーズ 1 （要件収集）​中、担当者は要件文書を作成し、次のような質問を明確にします。

• PDPのどの部分に評価が表示されますか？
• 新しいスタンドアロンブロックにするか、既存のPDP ドロップインコンポーネント内でスロットをカスタマイズするか。
• APIが使用できない場合やデータが返されない場合、フォールバックはどうなりますか？
• 評価はPLP （製品リスト）にも表示されますか、それともPDPのみですか？
• デザインスペックやモックアップはありますか？

プロジェクトの要件にもとづいて、これらの質問に答えましょう。 担当者は要件ドキュメントを更新し、フェーズを「完了」とマークします。

フェーズ 2 （アーキテクチャ プランニング）​中、エージェントはアーキテクチャを提案する前にドキュメントとコードベースを調査します。 エージェントには次の操作を期待します。

• PDP ドロップインコンテナ、スロット、およびイベントペイロードについて、Commerceのドキュメントを検索します。
• blocks ディレクトリとscripts/initializers/ フォルダーをスキャンして、既存のPDP関連コードを探します。
• 使用可能なコンテナとスロットコンテキストシェイプのTypeScript定義について説明します。

次に、エージェントは次のようなアーキテクチャオプションを表示します。

• オプション A:​既存のPDP ドロップインスロットをカスタマイズして、製品タイトルの近くに評価を挿入します。軽いタッチでアップグレードに対応します。
• オプション B: APIから個別に取得する新しいスタンドアロン product-ratings ブロックを作成します。より柔軟で分離されています。
• オプション C:​製品SKUのPDP ドロップインイベントもリッスンする新しいブロックを作成します。これは、ハイブリッドなアプローチです。

プランには、API統合、パフォーマンスに関する考慮事項（遅延読み込み、キャッシュ）、セキュリティ（入力のサニタイズ）、テストアプローチの詳細も含まれています。

アーキテクチャプランを確認し、続行するようにエージェントに指示します。

フェーズ 3 （実装アプローチ）​中、エージェントは次のいずれかを選択するよう求めます。

• オプション A: コードを生成する前に、詳細な実装計画を確認します（最初にすべてのファイル、パターン、コード構造を参照）。
• オプション B: コード生成に直接進みます。

お好みのアプローチを選択してください。

フェーズ 4 （実装）​中、エージェントは選択したアーキテクチャに基づいてコードを生成します。 アプローチに応じて、エージェントはいくつかの専門的なスキルを使用します。

• コンテンツモデリング：​新しいブロックが必要な場合、エージェントは、API エンドポイント URLを持つ構成テーブルなど、作成者に適したコンテンツ構造を設計します。
• ブロック開発： エージェントは、JavaScriptのデコレーション関数、スコープ CSS スタイル、アクセシビリティ用のARIA ラベル、読み込みエラーの状態の処理など、Edge Delivery Servicesの規則に従ってブロックファイルを作成します。
• ドロップインのカスタマイズ： アーキテクチャでスロットのカスタマイズを使用している場合、エージェントは正しいコンテナをインポートし、製品タイトルの近くに検証済みのスロットを使用し、現在のSKUの製品データイベントを購読します。

生成されるコードを確認し、必要に応じて質問したり、担当者に連絡したりできます。 エージェントは、コード生成が完了すると、実稼動準備状況のサマリーを生成します。

フェーズ 4.5 （テスト）​中、エージェントは実装をテストすることを提案します。 受け入れる場合、担当者：

• 適切なスクリプトとスタイルを使用してローカルテストページを作成します。
• 開発サーバーを開始します。
• ビジュアルレンダリング、インタラクティブ性、レスポンシブ動作、アクセシビリティ、パフォーマンスに対して、ブラウザベースの検証を実行します。
• 結果を含む構造化テストレポートを生成します。

ブラウザーに従って、動作を確認し、問題を報告します。

コードベースの変更を確認し、製品ページの更新を確認します。

開発環境とブラウザーに次の変更が表示されます。

• 製品評価コンポーネントが自動的に作成されます。
• コンポーネントは、選択したアーキテクチャに応じて、​ ドロップインスロット ​またはスタンドアロンブロックとしてPDPに統合されます。
• 星は、APIの評定値に基づいて適切な塗りつぶしの縦横比で表示されます。

{width="600" modal="regular"}

開始する前：​次のモック画像を保存し、ストアフロント担当者とのチャットに貼り付けます。

{width="600" modal="regular"}

参照画像をガイドとして使用して定格分布モーダルを作成するには、次の手順に従います。

• 評価の分布を表す追加データを返すようにAPIを更新します。
• API コントラクトを更新します。
• ストアフロントのコードベースで契約を更新します。
• ストアフロントエージェントに、参照画像と更新されたAPI契約を使用して、PDP ページに評価ディストリビューションを追加するように依頼します。

コードベースの次の変更を確認し、製品ページで更新を確認します。

• エージェントによるビジュアルモックアップの解釈
• アクセシビリティに適切なHTML構造を使用しているか
• ポジショニングとインタラクションの状態の処理方法