storefront-best-practices

Eコマースストアフロントのベストプラクティス

UI/UX パターン、コンポーネント設計、レイアウト構成、SEO 最適化、モバイル対応を網羅した、最新のコンバージョン率の高い Eコマースストアフロントを構築するための包括的なガイダンスです。

適用するタイミング

ストアフロントに関する作業では、どのようなタスクでも必ずこのスキルを読み込んでください。

• チェックアウトページ／フローの追加 - 決済、配送、注文手続き
• カートの実装 - カートページ、カートのポップアップ、カートへの追加機能
• 商品ページの作成 - 商品詳細、商品一覧、商品グリッド
• ナビゲーションの作成 - ナビゲーションバー、メガメニュー、フッター、モバイルメニュー
• Medusa バックエンドとの連携 - SDK のセットアップ、カート、商品、決済
• ストアフロントのあらゆるコンポーネント - ホームページ、検索、フィルター、アカウントページ
• Eコマースストアフロントをゼロから構築する
• 既存のショッピング体験とコンバージョン率を改善する
• ユーザビリティ、アクセシビリティ、SEO を最適化する
• モバイル対応の Eコマース体験を設計する
• ストアフロントをエージェントフレンドリーにする（AI ショッピングエージェント、AI 検索、エージェント型コマース）

このスキルを適用するきっかけとなるプロンプトの例：

• 「チェックアウトページを追加して」
• 「ショッピングカートを実装して」
• 「商品一覧ページを作成して」
• 「Medusa バックエンドに接続して」
• 「ナビゲーションメニューを追加して」
• 「ストアのホームページを構築して」
• 「ストアをエージェント対応／AI フレンドリーにして」

重要：必要に応じてリファレンスファイルを読み込む

⚠️ UI コンポーネントを作成する前に、必ず reference/design.md を読み込んでください

• 既存のデザイントークン（色、フォント、余白、パターン）を確認します
• 一貫性のないスタイルの導入を防ぎます
• ブランドの一貫性を保つための指針を提供します
• 新しいストアフロントだけでなく、すべてのコンポーネントで必須です

実装内容に応じて、以下のリファレンスを読み込んでください。

• 新しいストアフロントを始める場合 → ユーザーの好みを確認するため、最初に必ず reference/design.md を読み込みます
• バックエンド API に接続する場合 → 最初に必ず reference/connecting-to-backend.md を読み込みます
• Medusa バックエンドに接続する場合 → SDK のセットアップ、価格設定、地域、Medusa のパターンについて reference/medusa.md を必ず読み込みます
• ホームページを実装する場合 → reference/components/navbar.md、reference/components/hero.md、reference/components/footer.md、reference/layouts/home-page.md を必ず読み込みます
• ナビゲーションを実装する場合 → reference/components/navbar.md を必ず読み込み、必要に応じて reference/components/megamenu.md も読み込みます
• 商品一覧を作成する場合 → 最初に reference/layouts/product-listing.md を必ず読み込みます
• 商品詳細を作成する場合 → 最初に reference/layouts/product-details.md を必ず読み込みます
• チェックアウトを実装する場合 → 最初に reference/layouts/checkout.md を必ず読み込みます
• SEO を最適化する場合 → 最初に reference/seo.md を必ず読み込みます
• ストアをエージェントフレンドリーにする場合、または商品ページ、カートへの追加、検索、フッター、robots.txt、サイトマップ、構造化データを作成する場合 → reference/agent-friendly.md を必ず読み込みます
• モバイル向けに最適化する場合 → 最初に reference/mobile-responsiveness.md を必ず読み込みます

最低要件： 実装を始める前に、具体的なタスクに関連するリファレンスファイルを少なくとも1～2個読み込んでください。

計画と実装のワークフロー

重要：ストアフロント機能の実装計画を作成する場合は、以下の内容を計画に含めてください。

計画に含まれる各コンポーネント、ページ、レイアウト、機能を実装する際は、次の手順に従います。

1. 実装を始める前に、このスキルを再確認する
2. 構築するコンポーネント／ページに応じて、上記の関連リファレンスファイルを読み込む
3. リファレンスファイルのパターンとガイダンスに従う
4. 既知の落とし穴を避けるため、「よくある間違い」のセクションを確認する

計画の構成例：

Task 1: Implement Navigation
- Load reference/components/navbar.md
- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)
- Refer to skill for common mistakes (e.g., hardcoding categories)

Task 2: Implement Product Listing Page
- Load reference/layouts/product-listing.md
- Follow pagination/filtering patterns from product-listing.md
- Use reference/components/product-card.md for product grid items
- Check skill for backend integration guidance

Task 3: Implement Checkout Flow
- Load reference/layouts/checkout.md
- Load reference/medusa.md for Medusa payment integration
- Follow component architecture recommendations (separate step components)
- Refer to skill for payment method fetching requirements

重要な理由：

• 計画は全体的な方針を示します
• リファレンスファイルは詳細な実装パターンを示します
• スキルファイルには、避けるべき重要な間違いが記載されています
• このワークフローに従うことで、一貫性とベストプラクティスを確保できます

Eコマースに特有の重要なパターン

アクセシビリティ

• 重要：カート数の更新にはaria-live="polite"が必要です - これがないと、スクリーンリーダーで通知されません
• すべてのカート／購入手続きの操作で、キーボードナビゲーションを確保してください

モバイル

• 画面下部に固定する要素では、必ずenv(safe-area-inset-bottom)を使用してください - 使用しないと、iOS のホームインジケーターによって購入ボタンが隠れてしまいます
• カート操作、バリエーション選択、数量ボタンのタッチ領域は、最低44pxを確保してください

パフォーマンス

• 折り返し位置より下の商品画像には、必ずloading="lazy"を追加してください - ブラウザーのデフォルト設定に頼らないでください
• モバイル向けに商品画像を最適化してください（500KB未満） - EC のトラフィックの大半はモバイルです

コンバージョン最適化

• ショッピングの流れ全体を通じて、明確な CTA を設置します
• 購入手続きの手間を最小限に抑えます（対応している場合はゲスト購入を提供します）
• 購入ボタンの近くに、信頼につながる情報（レビュー、セキュリティバッジ、返品ポリシー）を表示します
• 価格と送料を事前に明確に提示します

SEO

• 商品スキーマ（JSON-LD）は必須です - Google ショッピングやリッチスニペットに欠かせません
• PageSpeed Insightsを使って Core Web Vitals を測定します

エージェントへの対応

AI エージェント（ChatGPT、Claude、Perplexity、ブラウザーエージェント）はユーザーに代わって買い物をします。その多くは JavaScript を実行しません。詳細なガイダンスはreference/agent-friendly.mdを読み込んでください。主なルール：

• 商品名、通貨付きの表示価格、在庫状況は、必ずサーバー HTML に含めてください - curlで確認します
• カートに追加する操作は、<form method="post" action="...">内に、名前付きの<button type="submit">として配置する必要があります。バリエーション選択には、そのフォーム内でネイティブのラジオボタンまたは<select>を使用してください
• 検索は、GET URL（/search?q=）で機能し、サーバー側でレンダリングされた検索結果を返す必要があります
• AI エージェントをブロックしないでください（robots.txt、ミドルウェア、ホームページ／商品詳細ページ／カートの CAPTCHA、コンテンツを置き換えるゲート）
• 不明な商品ハンドルには、200 やホームページへのリダイレクトではなく、404 を返す必要があります

ビジュアルデザイン

• ストアフロントの UI では絵文字を絶対に使わないでください - 代わりにアイコンや画像を使用します（プロ意識に欠け、アクセシビリティにも問題があります）

バックエンド連携

• バックエンドの検出：モノレポの場合は、バックエンドのディレクトリを確認してください。不明な場合は、使用しているバックエンドをユーザーに確認します
• 動的なコンテンツをハードコードしないでください：カテゴリ、地域、商品、配送オプションなどは、常にバックエンドから取得してください - これらは頻繁に変わります
• API の構造を決めつけず、エンドポイントとデータ形式を確認してください

⚠️ 重要：バックエンド SDK メソッドの検証ワークフロー

バックエンドに接続するコードを書く前に、必ず次のワークフローに従ってください。

ステップ 1：一時停止 — まだコードを書かないでください

• バックエンド API または SDK メソッド（例：Medusa SDK、REST API、GraphQL）を呼び出すコードを書こうとしています
• 停止してください — 検証せずにコードの作成へ進んではいけません

ステップ 2：ドキュメントまたは MCP サーバーに問い合わせる

• MCP サーバーが利用可能な場合：正確なメソッドを問い合わせます（例：medusa MCP）
• MCP サーバーがない場合：公式ドキュメントを検索します
• 確認する項目：正確なメソッド名、パラメーター、戻り値の型

ステップ 3：見つけた内容を検証する

• ユーザーに声に出して伝えます：「[操作] に正しいメソッドを確認する必要があります。[MCP サーバー／ドキュメント] を確認します。」
• 見つけた内容をユーザーに示します：「[情報源] によると、メソッドは sdk.store.cart.methodName(params) です」
• メソッドのシグネチャとパラメーターを確認します

ステップ 4：その後でのみコードを書く

• ここで初めて、検証済みのメソッドを使用してコードを書けます
• 確認した正確なシグネチャを使用します

ステップ 5：TypeScript のエラーを確認する

• コードを書いた後、SDK 関連の TypeScript／型エラーがないか確認します
• SDK メソッドに型エラーがある場合、誤ったメソッド名または誤ったパラメーターを使用したことを意味します
• 型エラーは、正しく検証しなかった証拠です — ステップ 2 に戻ってください

これは任意ではありません — エラーを防ぐために必須です

次の行為は重大なエラーです。

• ❌ ドキュメント／MCP に明示的に問い合わせずに、バックエンド API／SDK を呼び出すコードを書く
• ❌ メソッド名やパラメーターを推測する
• ❌ SDK メソッドの TypeScript エラーを無視する（エラーはメソッドの使用方法が誤っていることを示します）
• ❌ このスキルのサンプルを検証せずにコピーする（サンプルが古くなっている可能性があります）
• ❌ SDK メソッドが REST API エンドポイントと一致すると決めつける

Medusa について

• Medusa の価格設定：価格はそのまま表示してください — 100 で割ってはいけません（Stripe とは異なり、Medusa では価格が表示形式で保存されます）
• ドキュメント MCP サーバー：https://docs.medusajs.com/mcp — 未インストールの場合はセットアップを推奨します
• Medusa 固有のパターン（地域、価格設定など）については、reference/medusa.md を読み込んでください

ルーティングのパターン

• 商品とカテゴリには必ず動的ルートを使用してください — 個別アイテム用の静的ページは作成しないでください
• 商品ページ：/products/[handle] や /products/$handle のような動的ルートを使用し、/products/shirt.tsx は使用しないでください
• カテゴリページ：/categories/[handle] や /categories/$handle のような動的ルートを使用し、/categories/women.tsx は使用しないでください
• フレームワークごとのパターン：
  • Next.js App Router：app/products/[handle]/page.tsx または app/products/[id]/page.tsx
  • Next.js Pages Router：pages/products/[handle].tsx
  • SvelteKit：routes/products/[handle]/+page.svelte
  • TanStack Start：routes/products/$handle.tsx
  • Remix：routes/products.$handle.tsx
• 理由：動的ルートなら個別のファイルを作成せずに、任意の数の商品／カテゴリに対応できます
• 静的ルートは保守が困難で、規模を拡大できません（商品ファイルを 1000 個作ることを想像してください）

パターン選択ガイド

実装パターンを選ぶ必要がある場合は、該当するリファレンスファイルを読み込んでください。

• チェックアウト戦略（シングルページ型かマルチステップ型か）→ reference/layouts/checkout.md を読み込む
• ナビゲーション戦略（ドロップダウンかメガメニューか）→ reference/components/navbar.md と reference/components/megamenu.md を読み込む
• 商品一覧表示戦略（ページネーションか無限スクロールか「もっと読み込む」か）→ reference/layouts/product-listing.md を読み込む
• 検索戦略（オートコンプリートかフィルターか自然言語か）→ reference/components/search.md を読み込む
• モバイルとデスクトップの優先順位 → reference/mobile-responsiveness.md を読み込む
• バリエーション選択（テキストかスウォッチかコンフィギュレーターか）→ reference/layouts/product-details.md を読み込む
• カートのパターン（ポップアップかドロワーかページ遷移か）→ reference/components/cart-popup.md と reference/layouts/cart.md を読み込む
• 信頼を示す要素の戦略 → reference/layouts/product-details.md と reference/layouts/checkout.md を読み込む

各リファレンスファイルには、状況に合ったパターンを選ぶための具体的な基準を含む判断フレームワークが記載されています。

クイックリファレンス

全般

reference/connecting-to-backend.md    - Framework detection, API setup, backend integration patterns
reference/medusa.md                    - Medusa SDK integration, pricing, regions, TypeScript types
reference/design.md                    - User preferences, brand identity, design systems
reference/seo.md                       - Meta tags, structured data, Core Web Vitals
reference/agent-friendly.md            - AI agent access, machine-readable product data, operable forms, llms.txt, UCP
reference/mobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions

コンポーネント

reference/components/navbar.md         - Desktop/mobile navigation, logo, menu, cart icon, load for ALL pages
reference/components/megamenu.md       - Category organization, featured products, mobile alternatives
reference/components/cart-popup.md     - Add-to-cart feedback, mini cart display
reference/components/country-selector.md - Country/region selection, currency, pricing, Medusa regions
reference/components/breadcrumbs.md    - Category hierarchy, structured data markup
reference/components/search.md         - Search input, autocomplete, results, filters
reference/components/product-reviews.md - Review display, rating aggregation, submission
reference/components/hero.md           - Hero layouts, CTA placement, image optimization
reference/components/popups.md         - Newsletter signup, discount popups, exit-intent
reference/components/footer.md         - Content organization, navigation, social media, load for ALL pages
reference/components/product-card.md   - Product images, pricing, add to cart, badges
reference/components/product-slider.md - Carousel implementation, mobile swipe, accessibility

レイアウト

reference/layouts/home-page.md         - Hero, featured categories, product listings
reference/layouts/product-listing.md   - Grid/list views, filters, sorting, pagination
reference/layouts/product-details.md   - Image gallery, variant selection, related products
reference/layouts/cart.md              - Cart items, quantity updates, promo codes
reference/layouts/checkout.md          - Multi-step/single-page, address forms, payment
reference/layouts/order-confirmation.md - Order number, summary, delivery info
reference/layouts/account.md           - Dashboard, order history, address book
reference/layouts/static-pages.md      - FAQ, about, contact, shipping/returns policies

機能

reference/features/wishlist.md         - Add to wishlist, wishlist page, move to cart
reference/features/promotions.md       - Promotional banners, discount codes, sale badges

一般的な実装パターン

新しいストアフロントの開始

重要：以下の各ステップを実装する前に、参照先のファイルを読み込んでください。

1. Discovery Phase → Read design.md for user preferences
2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md
3. Core Components → Implement navbar.md, footer.md
4. Home Page → Read home-page.md
5. Product Browsing → Read product-listing.md, product-card.md, search.md
6. Product Details → Read product-details.md, product-reviews.md
7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md
8. User Account → Read account.md
9. Additional Features → Read wishlist.md, promotions.md
10. Optimization → SEO audit (seo.md), agent-friendliness audit (agent-friendly.md), mobile testing (mobile-responsiveness.md)

実装計画を作成する場合でも、各ステップの実装時にはスキルを参照し、関連するリファレンスファイルを読み込んでください。

ショッピングフローのパターン

Browse → View → Cart → Checkout

Browse:   home-page.md → product-listing.md
View:     product-details.md + product-reviews.md
Cart:     cart-popup.md → cart.md
Checkout: checkout.md → order-confirmation.md

コンポーネント選択ガイド

商品グリッドとフィルタリングの場合 → product-listing.md と product-card.md 商品カードの場合 → product-card.md ナビゲーションの場合 → navbar.md と megamenu.md 検索機能の場合 → search.md チェックアウトフローの場合 → checkout.md プロモーションとセールの場合 → promotions.md

デザイン上の考慮事項

実装する前に、以下を検討してください。

1. ユーザーの好み - design.md を読んで、好みのデザインスタイルを確認します
2. ブランドアイデンティティ - ブランドに合った色、タイポグラフィ、トーン
3. ターゲットオーディエンス - B2C か B2B か、人口統計、デバイスの利用状況
4. 商品タイプ - ファッション、電子機器、食料品などによってレイアウトの選択が変わります
5. ビジネス要件 - 複数通貨、複数言語、地域固有の要件
6. バックエンドシステム - API の構成がコンポーネントの実装に影響します

Medusa との統合

Medusa は、モダンで柔軟な E コマースバックエンドです。次のような場合に Medusa を検討してください。

• 新しい E コマースのストアフロントを構築する
• ヘッドレスコマースソリューションが必要
• マルチリージョン、マルチカレンシーの組み込みサポートが必要
• 強力なプロモーションおよび割引エンジンが必要
• 柔軟な商品モデリングが必要

Medusa との統合に関する詳しいガイダンスは、reference/medusa.md を参照してください。一般的なバックエンドのパターンについては、reference/connecting-to-backend.md を参照してください。

フレームワークに依存しない設計

すべてのガイダンスはフレームワークに依存しません。コード例では、説明に役立つ場合に React/TypeScript を使用していますが、以下にもパターンを適用できます。

• Next.js
• SvelteKit
• Tanstack Start
• その他のモダンなフロントエンドフレームワーク

最小限の実用機能

リリースに必須（ショッピングの基本フロー）：

• カート、カテゴリー、検索を備えたナビゲーションバー
• フィルタリングとページネーションを備えた商品一覧
• バリエーションを選択できる商品詳細
• カートに追加する機能
• 商品を管理できるカートページ
• チェックアウトのフロー（配送、支払い、確認）
• 注文確認ページ

あると便利（時間があれば追加）：

• 関連商品のレコメンデーション
• 商品レビューと評価
• ウィッシュリスト機能
• 商品ページでの画像ズーム
• モバイルでの下部ナビゲーション
• ナビゲーション用メガメニュー
• ニュースレターの登録
• 商品比較
• クイックビューモーダル

ユーザー次第（実装前に確認）：

• ゲストチェックアウトとログイン必須のどちらにするか
• アカウントダッシュボードの機能
• 多言語対応
• 多通貨対応
• ライブチャットサポート
• エージェント型コマースプロトコル（UCP profile、MCP agent endpoint、OAuth discovery）— reference/agent-friendly.md を参照

避けるべきECサイトのよくある失敗

実装前に、ECサイト特有のよくある落とし穴に注意してください。

1. カートとナビゲーションに関する失敗

• ❌ モバイルのハンバーガーメニューにカート表示を隠す（常に表示しておきます）
• ❌ カート数のリアルタイム更新を表示しない
• ❌ 重大：カート数に aria-live="polite" がない — これがないと、スクリーンリーダーはカートの更新を読み上げません
• ❌ カートのポップアップにバリエーションの詳細（サイズ、色など）を表示せず、商品タイトルだけを表示する
• ❌ ドロップダウンのコンテンツにマウスを合わせるとメガメニューが閉じる（トリガーまたはドロップダウンにマウスを合わせている間は開いたままにする必要があります）
• ❌ 重大：メガメニューの配置ミス — よくある失敗は次の3つです。
  • ❌ ナビゲーションバーに position: relative が設定されていない（メガメニューが正しく配置されません）
  • ❌ メガメニューをナビゲーションバーではなくトリガーボタンを基準に配置する（メガメニューに absolute left-0 を使用します）
  • ❌ メガメニューが全幅に広がらない（w-auto だけでなく、right-0 または w-full を使用する必要があります）
• ❌ バックエンドから取得せず、カテゴリー、注目商品、その他の動的コンテンツをハードコードする
• ❌ カテゴリーナビゲーションで現在のページが明確に示されていない

2. 商品閲覧に関する失敗

• ❌ 商品やカテゴリーに静的ルートを作成する（/products/shirt.tsx ではなく、/products/[handle] のような動的ルートを使用します）
• ❌ 「商品が見つかりません」という空の状態と、役立つ提案を表示しない
• ❌ 商品の取得中にローディングインジケーターを表示しない
• ❌ SEOに適したURL（検索エンジン向け）を使用せずにページネーションする
• ❌ ページを再読み込みするとフィルターの選択状態が保持されない

3. 商品詳細に関する失敗

• ❌ バリエーション（サイズ、色など）を選択する前に「カートに追加」を有効にする
• ❌ 商品画像を最適化しない（大きく、圧縮されていない画像を使用する）
• ❌ カートに追加した後、商品ページから移動する（ページにとどまります）
• ❌ アイコンや画像の代わりにUIで絵文字を使用する（プロフェッショナルさに欠け、アクセシビリティ上の問題もあります）

4. デザインと一貫性に関する失敗

• ❌ 重大：UIコンポーネントを作成する前に reference/design.md を読まない — 色、フォント、スタイルに一貫性がなくなります
• ❌ 既存のテーマを確認せずに新しい色を導入する
• ❌ すでに使用されているフォントを確認せずに新しいフォントを追加する
• ❌ テーマトークンがあるのに、任意のTailwind値を使用する
• ❌ Tailwindのバージョン（v3かv4か）を確認しない — 構文エラーの原因になります

5. チェックアウトとコンバージョンに関する失敗

• ❌ チェックアウトにアカウント作成を必須にする（バックエンドが対応している場合はゲストチェックアウトを提供します）
• ❌ バックエンドから支払い方法を取得せず、利用可能な支払い方法を決めつけたり、支払い方法の選択を省略したりする
• ❌ チェックアウトのステップが複雑すぎる（4ステップ以上ではコンバージョン率が下がります）— 最適なのは3ステップです：配送先情報、配送方法と支払い、確認
• ❌ 信頼につながる情報（安全なチェックアウトのバッジ、返品ポリシーへのリンク）がない
• ❌ チェックアウト中の在庫切れエラーを適切に処理しない 6. モバイル体験に関するよくある間違い
• ❌ タップ対象が44x44pxより小さい（ボタン、リンク、フォームフィールド）
• ❌ モバイルでデスクトップスタイルのホバーメニューを使う（代わりにタップ／クリックを使用）
• ❌ モバイル向けに画像を最適化していない（大きなデスクトップ用画像を読み込む）
• ❌ モバイル固有のパターンがない（ボトムナビゲーション、ドロワーフィルター）

7. パフォーマンスとSEOに関するよくある間違い

• ❌ SEO向けの構造化データ（Productスキーマ）がない
• ❌ 画像の遅延読み込みを明示的に指定していない（ブラウザーのデフォルト設定に頼らないでください）。スクロールしないと見えない位置にある画像には、必ずloading="lazy"を追加してください
• ❌ ソーシャル共有用のメタタグとOpen Graphがない
• ❌ Core Web Vitals（LCP、FID、CLS）を最適化していない。測定にはPageSpeed InsightsまたはLighthouseを使用してください

8. エージェントフレンドリーに関するよくある間違い（reference/agent-friendly.mdを参照）

• ❌ クライアントコンポーネントで商品データや価格を取得する（エージェントには空のシェルが表示されます）
• ❌ <div onClick>や、周囲に<form action>がない<button>でカートに追加する
• ❌ ネイティブ入力要素やARIAの状態を使わず、単なる<div>／<span>でバリエーションのスウォッチを表示する
• ❌ aria-labelのないアイコンのみのボタン（カート、検索、メニュー、ウィッシュリスト）
• ❌ GETの結果ページがない、JSのみの検索オーバーレイ
• ❌ robots.txt、ミドルウェア、WAFでAIエージェント／検索ボットをブロックする（トレーニング用クローラーのブロックは問題ありません）
• ❌ /からロケールパスへのIPベースのリダイレクトを強制する
• ❌ 不明な商品URLが200を返す、またはホームにリダイレクトする（ソフト404）

9. バックエンド統合に関するよくある間違い

• ❌ エラー：5段階の検証ワークフローに従わず、バックエンドAPI／SDKを呼び出すコードを書く - 必ず、1）一時停止する、2）ドキュメント／MCPを参照する、3）ユーザーに確認する、4）コードを書く、5）型エラーを確認する、の順に実施してください
• ❌ エラー：SDKメソッドのTypeScriptエラーを無視する - 型エラーは、メソッド名またはパラメーターを誤って使用していることを意味します。ドキュメント／MCPで再確認してください
• ❌ エラー：APIメソッド名、SDKメソッド、またはパラメーターを推測する - 使用前に、正確なメソッドシグネチャを必ず確認してください
• ❌ エラー：利用可能なDocs MCPサーバーを使用しない - Medusaバックエンドを使用する場合は、必ずDocs MCPサーバーでメソッドを確認してください
• ❌ エラー：最新であることを確認せずにコード例をコピーする - 例は古くなっている場合があるため、必ず事前に確認してください
• ❌ 使用中のバックエンドを特定しない（モノレポを確認し、不明な場合はユーザーに尋ねてください）
• ❌ バックエンドのドキュメントやMCPサーバーを確認せずに、APIの構造を決めつける
• ❌ カテゴリー、リージョン、商品などの動的コンテンツをバックエンドから取得せずにハードコードする
• ❌ @medusajs/typesパッケージを使用せず、Medusaエンティティのカスタム型を定義する
• ❌ 公開可能なAPIキーを設定せずにMedusa SDKを初期化する（マルチリージョンのストアと商品価格に必要です）
• ❌ region_idクエリパラメーターを渡さずにMedusaの商品を取得する（価格が取得できない、または誤った価格になります）
• ❌ Medusaのチェックアウトで全ての国を表示する（カートのリージョンに対応する国のみ表示してください）
• ❌ Medusaの価格を100で割る（Medusaは価格をStripeのようなセント単位ではなく、そのまま保存します）
• ❌ Medusa SDK用のVite SSR設定がない（vite.config.tsにssr.noExternal: ['@medusajs/js-sdk']を追加してください）
• ❌ Medusaのストアフロントをポート8000以外で実行する（CORSエラーが発生します。Medusaバックエンドはデフォルトでポート8000を想定しています）
• ❌ API呼び出しの読み込み中、エラー、空の状態を処理しない
• ❌ サーバー側で行うべきAPI呼び出しをクライアント側で行う（SEO、セキュリティ）
• ❌ 適切なエラーメッセージを実装しない（「エラーが発生しました」ではなく「商品は在庫切れです」）
• ❌ キャッシュを無効化しない（商品データ、価格、在庫が古いままになります）
• ❌ 注文確定後にカートの状態をクリアしない - Context／localStorage／キャッシュからカートがリセットされていないため、カートのポップアップに古い商品が表示されます