dee0917/commercecraft-agent-skill

全自動純フロントエンドトップレベルEC独立店舗構築エンジン（Auto E-Commerce Frontend Engine）

核心理念：極限の視覚美学、ハードコアなエンジニアリングアーキテクチャ、100%フロントエンドクローズドループ、ゼロ外部依存。

本スキルは、成熟したDTC ECモデルとモダンフロントエンドエンジニアリングの実務を統合し、商用レベル、ゼロプレースホルダー、実際のショッピングとチェックアウト状態遷移を備えたモダンなフロントエンドEC体験を提供することに特化しています。

実行言語仕様:

• ブランド名、商品タイトル、仕様パラメータ、UIテキスト → 英語のみ、国際ブランドの品質感を演出。
• 開発ログ、進捗レポート、技術説明、ユーザーとの対話 → 繁体字中国語。
• コード内の変数、関数、インターフェース定義 → 英語キャメルケース（camelCase / PascalCase）、ピンイン命名は絶対禁止。

---

🤖 5つの仮想ロールとスキルマトリックス（Agent Team Architecture）

サイト構築プロセス実行時、AIエージェントは5つの専門ロールに切り替わり、順序立てて推進し、相互に検証します。

役割 (Role)	中核的責務	主要スキルタグ (Skills)
1. Project Orchestrator	ブランドポジショニング、カテゴリ選定、実行計画のスケジューリングとクロスフェーズ調整	prd, brainstorming, executing-plans, writing-plans
2. Chief Creative Director	ブランドのVibe（雰囲気）定義、色彩コントラスト、フォントシステム、高品質なタイポグラフィ	ui-ux-pro-max, brand-guidelines, canvas-design, frontend-design
3. Lead Full-Stack Architect	TypeScriptによる厳格なインターフェース定義、Zustand状態管理、RWDコンポーネントとルーティングの実装	web-artifacts-builder, frontend-design, react-best-practices, tailwindcss
4. Content Strategist	プロフェッショナルな商品説明、ストーリーテキスト、SEOキーワード、カスタマーレビューの設計	content-research-writer, internal-comms, brand-guidelines, doc-coauthoring
5. QA & Compliance	ゼロプレースホルダー監査、Consoleエラー調査、ビルド検収、7層品質ゲートチェック	verification-before-completion, webapp-testing, systematic-debugging, audit

---

🚀 全ライフサイクル実行フロー（Lifecycle Phases）

ユーザー発行: 「[カテゴリ/スタイル]のECサイトを生成して」

┌─ Phase 0: ゼロトレラントルールと心理学ルールの読み込み (P0)
│  ├─ 📖 references/anti-patterns.md を読み込む（18のゼロトレラントルール）
│  └─ 📖 references/ux-psychology-ecommerce.md を読み込む（CRO心理学原則）
│
├─ Phase 1: クリエイティブシードとデザインシステムの生成 (Creative & System Generation)
│  ├─ 🎲 ブランドテーマを決定（例: Minimal Desk Aesthetics, Luxe Aromatherapy, Tech Gear）
│  ├─ 🎨 Creative Directorが実行: カラーパレット（60-30-10ルール）とフォント（Display / Body）を決定
│  ├─ ✍️ Content Strategistが実行: ブランドコアスローガンと8〜12項目の高精細商品データを生成
│  └─ 📝 プロジェクトPRDサマリーとデザイン決定事項を docs/DESIGN_DECISIONS.md に出力
│
├─ Phase 2: フロントエンドエンジニアリング構築 (Vite + React + TS + Tailwind)
│  ├─ 🏗️ プロジェクトスケルトンを初期化（Vite React-TS）
│  ├─ 📦 中核依存関係をインストール: zustand, react-router-dom, lucide-react, clsx, tailwind-merge, framer-motion, canvas-confetti
│  ├─ 📐 テンプレートファイル templates/ecommerce-types.ts をインポートし、強い型制約を確保
│  └─ 🛒 状態管理層を実装 (src/store/useCartStore.ts)。LocalStorageによる永続化を備える
│
├─ Phase 3: 11ページ完全ECルーティング実装 (100% Complete Routes)
│  ├─ 🏠 レイヤーA (コアショッピングクローズドループ): Home, Shop, ProductDetail, CartDrawer, Checkout, OrderSuccess
│  ├─ 👤 レイヤーB (ユーザー信頼センター): Profile, OrderHistory
│  └─ 📜 レイヤーC (コンプライアンスと信頼ページ): FAQ, ShippingPolicy, ReturnsRefunds, About
│
├─ Phase 4: CRO心理学強化とビジュアル昇華
│  ├─ ⏳ 希少性ラベルを注入（Scarcity: 「残り3点！」）
│  ├─ 🚚 送料無料しきい値までの差額プログレスバーを実装（「あと$Xで送料無料」）
│  ├─ ⭐ 実際のカスタマーレビュー（星評価）と購入アクティビティ（社会的証明）を埋め込む
│  ├─ 🏷️ Schema.org (Product, Offer) のJSON-LD構造化データを注入
│  └─ 🖼️ 高解像度のUnsplash商用写真画像を設定（ぼやけたプレースホルダーは禁止）
│
└─ Phase 5: 品質検収とワンクリックデリバリー (Quality & Delivery Gate)
   ├─ 🔨 npm run build を実行（TypeScriptエラー0、ビルド警告0を確保）
   ├─ 🔍 7層品質ゲート検査を実行（ゼロモック、ゼロ切れリンク）
   └─ 🚀 フロントエンドプレビューとVercelワンクリックデプロイガイドを提供

---

📋 11ページ全機能ルーティング仕様 (Page Requirements)

生成されるすべてのサイトは、以下の11ページの完全なルーティングを備える必要があります。空ページや404は絶対に許可されません。

1. トップページ (/)：

   • ヒーロービジュアルバナー（インパクトのある大きな画像、強力なCTA「ザ・コレクションを購入する」）。
   • 権威信頼バッジ（送料無料、30日保証、256ビットSSL、エシカルクラフト）。
   • おすすめ商品のウォーターフォールグリッド（Featured Products Grid）。
   • カテゴリ別クイックリンク（Shop by Categories）。
   • ブランドストーリーセクション（Brand Ethos）。
   • 実際のカスタマーボイス（ソーシャルプルーフの声）。
   • ニュースレター購読セクション（割引インセンティブ付き）。

2. 商品一覧 (/shop)：

   • 多次元フィルター：カテゴリフィルター、価格帯スライダー、タグフィルター。
   • リアルタイム並べ替え機能：人気順、価格の安い順、高い順、新着順。
   • インスタントキーワード検索ボックス（クライアントサイド検索）。
   • 空検索時の防御状態（リセットボタン付きの「該当商品がありません」表示）。

3. 商品詳細ページ (/product/:id)：

   • マルチアングルサムネイルプレビュー切り替え（画像ギャラリー）。
   • バリエーションセレクター：サイズ、カラー、スタイル。
   • 在庫切れ間近アラート（在庫<5の場合は琥珀色の警告表示）。
   • 数量増減コントローラー。
   • 「カートに入れる」（スライドインカートドロワー）と「今すぐ購入」（チェックアウトへ直行）の2つのボタン。
   • タブパネル：詳細仕様（Specifications）、配送と返品（Shipping）、実際のカスタマーレビュー（Reviews）。
   • 関連商品レコメンデーション（Recommended Products）。
   • Schema.org JSON-LDの注入。

4. サイドカートドロワー (CartDrawer)：

   • 全サイトのヘッダーにあるカートアイコンまたは「カートに入れる」ボタンをクリックすると、スムーズにスライドイン（Framer Motion / Transition）。
   • 送料無料までの残り金額を即時計算するプログレスバー（例：$100以上で送料無料）。
   • 商品リスト：サムネイル、商品名、選択バリエーション、数量増減、即時削除。
   • プロモコード入力ボックス（例： WELCOME10 で10%割引）。
   • 金額サマリー：小計、割引額、推定送料、合計金額。
   • 「レジに進む」ボタン。

5. チェックアウト (/checkout)：

   • 3ステップのチェックアウトUI：
     1. 連絡先と配送先（顧客情報）：氏名、メール、住所、電話番号。
     2. 配送方法の選択（配送方法）：標準（$0〜$5）、速達（$15）。
     3. 支払い方法のシミュレーション（支払い方法）：クレジットカード入力（自動フォーマット、セキュリティアイコン付き）、Apple Pay / PayPalクイックチェックアウトオプション。
   • 右側/下部のリアルタイム注文サマリーカード（注文概要スティッキーカード）。
   • 二重クリック防止、フォームフィールドのリアルタイムバリデーション。

6. 注文完了ページ (/order-success)：

   • 緑色の成功チェックアニメーションと祝賀紙吹雪エフェクト（canvas-confetti）。
   • ランダム生成された専用注文番号（例： #ORD-2026-89412）。
   • 完全な注文サマリー、配送先情報、予定到着日。
   • 「買い物を続ける」ボタン。

7. 注文追跡と履歴 (/orders)：

   • 注文番号またはメールアドレスを入力してシミュレーション注文進捗バーを表示（確認済み→処理中→発送済み→配達済み）。

8. 会員とお気に入り (/profile)：

   • シミュレーションユーザープロフィール、ウィッシュリストのクイックビュー。

9. よくある質問 (/faq)：

   • アコーディオンコンポーネント。注文、配送、返品、素材・お手入れなど、よくある質問をカバー。

10. 配送ポリシー (/shipping)：

    • 国内外の送料表、各国の配送所要日数、関税についての説明を含む。

11. 返品ポリシーとブランドストーリー (/returns & /about)：

    • 30日間返品交換保証条件、返品3ステップフロー、ブランド創業の理念を明確に記載。

---

🧠 EC心理学とコンバージョン率（CRO）強制実装ガイド

生成されるすべてのサイトには、以下の心理学的メカニズムを組み込む必要があります（詳細は references/ux-psychology-ecommerce.md を参照）。

1. ヒックの法則:
   • チェックアウトフォームはデフォルトで簡潔にし、不要な必須でないフィールドを減らす。
   • ナビゲーションメニューの第一階層は5項目以内にする。
2. アンカリング効果:
   • セール商品には元値の取り消し線を並べて表示（例： ~~$120.00~~ $89.00）、節約額を示すラベル $31お得 を付ける。
3. 希少性と緊急性:
   • 商品詳細ページに動的かつランダムに「この価格での在庫は残り2点です」と表示。
   • チェックアウトページに「あなたのカートに10:00分間確保されています」（オプションでタイマー）と表示。
4. 社会的証明:
   • トップページと詳細ページに実際の購入者による確認バッジ（Verified Buyer）を表示。
   • 商品リストカードに平均評価点（例： ★ 4.9（128件のレビュー））を表示。
5. 損失回避:
   • カートの送料無料プログレスバーで動的に通知：「あと$12で送料無料！」。

---

🛠️ 状態管理アーキテクチャ仕様（Zustand + LocalStorage）

疎結合でデバウンスされたZustand Storeを採用し、ページ更新後もカートデータが失われないようにします。

// src/store/useCartStore.ts テンプレート
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
import { CartItem, Product } from '../types';

interface CartState {
  items: CartItem[];
  isOpen: boolean;
  promoCode: string | null;
  discountRate: number;
  openCart: () => void;
  closeCart: () => void;
  addItem: (product: Product, quantity?: number, selectedVariant?: string) => void;
  removeItem: (itemId: string) => void;
  updateQuantity: (itemId: string, quantity: number) => void;
  applyPromoCode: (code: string) => { success: boolean; message: string };
  clearCart: () => void;
  getSubtotal: () => number;
  getTotal: () => number;
}

---

🛡️ デリバリー品質防衛ライン（7層検収ゲート）

成果物をユーザーに提出する前に、QAロールが以下の項目を一つずつ検証し、合格する必要があります。

1. 画像切れゼロ: すべての画像URLが正常に読み込まれ、サイズが適切であり、loading="lazy" と alt 属性を持っていること。
2. リンク切れゼロ: サイト全体のナビゲーション、フッターリンク、ボタンがすべてクリック可能で、対応する11ページのルーティングに遷移すること。
3. プレースホルダーゼロ: Lorem Ipsum、商品1、$0.00 などの不誠実なテキストの使用を禁止。すべてのテキストがブランドトーンに合致していること。
4. カートクローズドループ完了: カートに追加 → ドロワーがスライドイン → 数量変更で金額が連動 → クーポン適用で割引 → チェックアウト送信 → 注文完了ページに遷移し注文番号を取得、までの一連の流れが動作すること。
5. RWDレスポンシブ保証: モバイル（375px）、タブレット（768px）、デスクトップ（1280px+）のいずれの画面サイズでも、水平方向のはみ出しやレイアウト崩れがないこと。
6. SEO構造化: 商品詳細ページで正しい application/ld+json（Schema.org Product）が出力されていること。
7. プロダクションビルド検証: npm run build をエラーなく実行でき、dist/ ディレクトリが出力されること。