glmv-prd-to-app

GLM-V PRD-to-App：フルスタックアプリケーションビルダー

言語：ユーザーが使用する言語と同じ言語で応答します。コードコメントも同じ言語にしてください。

PRD、プロトタイプ、リソースから、完成したデプロイ済みの Web アプリケーションを構築します。 最終的なアプリケーションは、bash /workspace/start.sh を 1 回実行するだけで完全に再現できる必要があります。

---

フェーズ 0：資料の把握と分析

何よりも先に、作業対象を把握してください。

0a. すべての入力を特定する

/workspace/prd.md              ← Product requirement document
/workspace/prototypes/*.jpg    ← UI prototype images (the visual truth)
/workspace/resources/**/*      ← Images, videos, icons, and other assets

資料が別の場所にある場合は、それに応じて対応してください。PRD を最後まで読んでください。

0b. プロトタイプの詳細分析

すべてのプロトタイプ画像について：

1. Read ツールを使って各画像を確認します。マルチモーダル機能を使い、画像を直接調べてください。

2. 各画像について、以下を記録します。

   • ページの識別：どのページ／ビューを表しているか
   • レイアウト構造：ヘッダー、サイドバー、メインコンテンツ、フッター、モーダル
   • コンポーネント一覧：すべてのボタン、フォーム、カード、テーブル、リスト、ナビゲーション要素
   • コンテンツ一覧：表示されているすべてのテキスト、数値、ラベル、プレースホルダーコンテンツ
   • 色の抽出：プライマリ、セカンダリ、アクセント、背景、テキストの色（16 進数値）
   • タイポグラフィ：フォントサイズ、ウェイト、確認できる階層
   • インタラクティブな状態：ホバー効果、アクティブなタブ、選択中の項目、トグル
   • データパターン：リスト／テーブル／カードに表示されるデータ。これをシードデータに反映します

3. プロトタイプのページ間のナビゲーションフローを示すページマップを作成します。

0c. リソース一覧

/workspace/resources/ 内のすべてのファイルを一覧にし、各ファイルがプロトタイプのどこに表示されるかを対応付けます。 関連するすべてのリソースファイルを最終的なアプリケーションで使用してください。

---

フェーズ 1：システム設計ドキュメント

包括的な設計ドキュメントを /workspace/docs/design.md に作成します。

1a. データモデル

各エンティティについて、以下を明記します。

• テーブル／コレクション名
• 型、制約、デフォルト値を含むすべてのフィールド
• リレーションシップ（外部キー、多対多）
• クエリパターンに必要なインデックス
• コンテンツの対応付け：どのプロトタイプ要素がどのフィールドに対応するか

例：

products table:
  id          SERIAL PRIMARY KEY
  name        VARCHAR(200) NOT NULL    ← from product card title
  price       DECIMAL(10,2) NOT NULL   ← from product card price label
  image_url   TEXT NOT NULL             ← from product card image
  category_id INTEGER REFERENCES categories(id) ← from category filter
  ...

1b. API 設計

ページ上のすべての操作について、API エンドポイントを定義します。

• メソッド＋パス
• リクエストのパラメーター／本文のスキーマ
• 例を含むレスポンスのスキーマ
• この API を呼び出すプロトタイプ上の操作
• エラーレスポンス

1c. フロントエンドアーキテクチャ

• コンポーネント階層（ツリー構造）
• プロトタイプのページに対応するルート定義
• 状態管理の方針
• 各プロトタイプページとコンポーネントの対応関係

1d. 技術スタック

PRD の複雑さに基づいて選択します。推奨されるデフォルトは以下のとおりです。

レイヤー	選択肢	使用するタイミング
フロントエンド	React + TypeScript + Vite	SPA のデフォルト
フロントエンド	Next.js	SSR／SEO が必要な場合
スタイリング	Tailwind CSS	デフォルト
バックエンド	Node.js + Express	シンプルな API
バックエンド	Python + FastAPI	PRD に Python の記載がある場合
データベース	SQLite	シンプルなアプリ、テーブル数が 10 未満の場合
データベース	PostgreSQL	複雑なアプリ、リレーションシップがある場合
ORM	Prisma (Node) / SQLAlchemy (Python)	バックエンドに合わせる

選択した技術とその理由を記録します。

1e. ディレクトリ構成

/workspace/
├── frontend/          ← or client/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── services/   ← API client
│   │   ├── types/
│   │   └── assets/     ← copied from /workspace/resources
│   └── ...
├── backend/           ← or server/
│   ├── src/
│   │   ├── routes/
│   │   ├── models/
│   │   ├── controllers/
│   │   ├── middleware/
│   │   └── seed/
│   └── ...
├── docs/
│   ├── design.md
│   └── README.md
├── start.sh
└── prd.md

---

フェーズ 2：シードデータの生成

シードデータは重要です。初回起動時からアプリを実際のものらしく見せる役割を果たします。

ルール

1. プロトタイプから抽出する：プロトタイプ画像に表示されているテキスト、画像、数値はすべて、シードデータに含める必要があります。各プロトタイプ画像をもう一度確認し、内容を書き起こしてください。

2. 漏れなく網羅する：

   • すべてのリスト／テーブルについて、プロトタイプに表示されている項目数と完全に一致させてください
   • すべてのカードについて、プロトタイプと一致する内容にしてください
   • すべてのドロップダウンについて、プロトタイプと一致する選択肢を用意してください
   • ナビゲーション項目をプロトタイプのナビゲーションに一致させてください
   • 統計情報／カウンターをプロトタイプの数値に一致させてください

3. リソースファイルを使用する：/workspace/resources/ のリソースファイル（画像、動画、アイコン）をシードデータのエントリーに対応付けてください。相対パスを使うか、public/static ディレクトリにコピーしてください。

4. プレースホルダーを使用しない：「Lorem ipsum」、「Test Item 1」、「placeholder.com」の画像は使わないでください。

5. すべての状態に対応する：PRDで指定されている空の状態、読み込み済みの状態、エラーの状態を網羅するデータを含めてください。

出力

シードデータは次のいずれかの形式で保存してください：

• SQL シードファイル
• JSON フィクスチャ
• ORM シードスクリプト

/workspace/backend/src/seed/（または同等の場所）に配置してください。

---

フェーズ 3：バックエンドの実装

3a. データベーススキーマ

• すべてのテーブルのマイグレーションファイルを作成する
• 適切な制約、インデックス、外部キーを含める
• マイグレーションを実行し、正常に動作することを確認する

3b. API エンドポイント

設計ドキュメントに記載された各エンドポイントについて：

1. ルートハンドラーを実装する
2. 入力検証を追加する（型、必須フィールド、範囲を検証する）
3. 適切な HTTP ステータスコードを使ったエラーハンドリングを追加する
4. curl などを使ってテストし、レスポンス形式を確認する

3c. シードデータの読み込み

• 次の処理を行うシードスクリプトを実装する：
  • 既存データを消去する（シードを冪等に再実行できるようにする）
  • 依存関係の正しい順序でシードデータをすべて挿入する
  • リソースファイルを適切な静的配信先にコピーする
• シードデータがエラーなく読み込まれることを確認する

3d. 静的ファイルの配信

• リソースファイル（画像、動画など）を配信するようにバックエンドを設定する
• フロントエンドが適切な URL からアクセスできることを確認する

---

フェーズ 4：フロントエンドの実装

ここでは視覚的な忠実度が最も重要です。プロトタイプが決定的な参照元です。

4a. グローバルスタイルとトークン

コンポーネントを構築する前に、以下を設定します：

• プロトタイプの色に合わせたカラー変数
• プロトタイプのフォントに合わせたタイポグラフィスケール
• プロトタイプの間隔に合わせた間隔／サイズのシステム
• 共通コンポーネントのスタイル（ボタン、カード、入力欄など）

4b. ページごとの実装

各プロトタイプ画像について、順番に次を行います：

1. プロトタイプ画像をもう一度確認する — 内容を常に把握しておきます
2. レイアウトを正確に一致させてページコンポーネントを構築する：
   • 間隔と比率を一致させる
   • 色とタイポグラフィを一致させる
   • 視覚的な階層を一致させる
   • コンテンツの配置を一致させる
3. バックエンドへの API 呼び出しを接続する
4. 表示されている、または示唆されているインタラクションをすべて実装する：
   • ページ間のナビゲーション
   • フォーム送信
   • 検索とフィルタリング
   • 並べ替え
   • モーダルとダイアログ
   • 読み込み状態
   • エラー状態
   • ホバーエフェクト
   • アクティブ／選択状態

4c. リソースの統合

• /workspace/resources/ のリソースをすべてフロントエンドのアセットにコピーする
• コンポーネントから正しく参照する
• プロトタイプに合った適切なサイズで画像が表示されることを確認する

4d. レスポンシブ対応

• プロトタイプに表示されているビューポート幅に合わせる
• プロトタイプにモバイル表示がある場合は、レスポンシブブレークポイントを実装する

---

フェーズ 5：視覚的な検証ループ

このフェーズが、優れた実装と素晴らしい実装の違いを生みます。 すべてのページでこのループを繰り返してください。

5a. ページをスクリーンショットに出力する

Playwright を使って、実行中のアプリケーションをキャプチャします：

python ${SKILL_DIR}/scripts/render_page.py \
  --url "http://localhost:3000/page-path" \
  --output "/workspace/docs/screenshots/page_name.png" \
  --width 1280

5b. 視覚的な比較

プロトタイプとスクリーンショットの両方の画像を横に並べて確認します。

1. /workspace/prototypes/ からプロトタイプ画像を読み込みます
2. レンダリングされたスクリーンショットを読み込みます
3. 以下の項目を体系的に比較します。
   • レイアウト：セクションは適切な位置にありますか？
   • 色：色は一致していますか？
   • タイポグラフィ：フォントサイズや太さは適切ですか？
   • コンテンツ：プロトタイプのコンテンツはすべて含まれていますか？
   • 余白：マージンとパディングは近い値ですか？
   • 画像：すべての画像が表示されていますか？
   • コンポーネント：すべての UI コンポーネントが適切に配置されていますか？

5c. 相違点の修正

見つかった相違点ごとに、以下を行います。

1. 必要な CSS／コンポーネントの変更を特定します
2. 修正を適用します
3. 再度レンダリングして比較します

5d. 満足するまで繰り返す

ページごとに最大 3 回まで繰り返します。まず影響の大きい相違点に取り組みます。

---

フェーズ 6：統合テスト

6a. API ヘルスチェック

API ヘルスチェッカーを実行して、すべてのエンドポイントを確認します。

python ${SKILL_DIR}/scripts/check_api.py \
  --base-url "http://localhost:3000/api" \
  --endpoints-file "/workspace/docs/endpoints.json"

または、curl を使って各エンドポイントを手動でテストします。

curl -s http://localhost:3000/api/products | head -c 200

6b. エンドツーエンドのフロー確認

PRD で定義されたすべてのユーザーフローを確認します。

1. http://localhost:3000 でアプリを開きます
2. 各ページに移動します
3. 各インタラクティブ機能をテストします
4. データがデータベースから読み込まれることを確認します
5. フォームが正しく送信されることを確認します
6. 検索／フィルター／並べ替えが機能することを確認します

6c. 見つかった問題を修正

CORS、API URL の不一致、データ形式の不一致など、統合に関する問題に対処します。

---

フェーズ 7：デプロイスクリプト

すべてを一から動作させる単一のコマンドとなる /workspace/start.sh を生成します。

要件

スクリプトは以下を満たす必要があります。

1. 完全に自己完結していること。事前のセットアップを前提としないこと
2. クリーンな環境で動作すること
3. すべてのシステム依存関係（Node.js、Python、DB など）をインストールすること
4. 以前の状態をすべてクリーンアップすること
5. データベースを一からセットアップすること
6. すべてのマイグレーションを実行すること
7. すべてのシードデータを読み込むこと
8. 必要に応じてフロントエンドをビルドすること
9. バックエンドとフロントエンドの両方を起動すること
10. http://localhost:3000 でアプリを利用可能にすること

テンプレート

#!/bin/bash
set -e

echo "=== PRD-to-App: Starting deployment ==="

# 1. System dependencies
echo "[1/7] Checking system dependencies..."
# Install Node.js, npm, etc. if missing
# Install database if needed

# 2. Backend setup
echo "[2/7] Setting up backend..."
cd /workspace/backend
npm install  # or pip install -r requirements.txt

# 3. Database initialization
echo "[3/7] Initializing database..."
# Drop existing DB / reset
# Run migrations
# Load seed data

# 4. Frontend setup
echo "[4/7] Setting up frontend..."
cd /workspace/frontend
npm install

# 5. Copy resources
echo "[5/7] Copying resource files..."
# cp -r /workspace/resources/* /workspace/frontend/public/assets/

# 6. Start backend
echo "[6/7] Starting backend server..."
cd /workspace/backend
npm run dev &   # or equivalent
BACKEND_PID=$!

# 7. Start frontend
echo "[7/7] Starting frontend..."
cd /workspace/frontend
PORT=3000 npm run dev &
FRONTEND_PID=$!

echo ""
echo "=== Application is running at http://localhost:3000 ==="
echo "Backend PID: $BACKEND_PID"
echo "Frontend PID: $FRONTEND_PID"
echo "To stop: kill $BACKEND_PID $FRONTEND_PID"

wait

検証

start.sh の生成後、以下を行います。

1. chmod +x /workspace/start.sh
2. 実行します：bash /workspace/start.sh
3. 起動を待ちます
4. http://localhost:3000 が応答することを確認します
5. いくつかの API エンドポイントを抜き取りで確認します
6. 起動時の問題を修正します

---

フェーズ 8：ドキュメント

8a. ソフトウェア設計書（/workspace/docs/design.md）

フェーズ 1 ですでに作成済みです。実装中に加えた変更を反映します。

• 最終的なシステムアーキテクチャ
• 最終的なデータモデル（開発中に追加したフィールドを含む）
• 技術スタック
• デプロイアーキテクチャ
• API リファレンス

8b. README（/workspace/README.md）

# [Project Name]

## Overview
[From PRD product overview]

## Technology Stack
- Frontend: ...
- Backend: ...
- Database: ...

## Quick Start
\`\`\`bash
bash start.sh
\`\`\`
Then visit http://localhost:3000

## Project Structure
[Directory tree]

## Database
[Schema overview, how to re-seed]

## API Reference
[Key endpoints]

---

成果物チェックリスト

完了を宣言する前に、すべての項目を確認します。

• PRD の機能をすべて実装済み。未対応の機能がない
• プロトタイプの全ページを作成済み。ページを統合または省略していない
• プロトタイプとの視覚的な一致をスクリーンショット比較で確認済み
• リソースファイルをプロトタイプ内で使用されている箇所にすべて反映済み
• シードデータがプロトタイプのコンテンツと完全に一致
• すべての API エンドポイントが動作し、正しいデータを返す
• すべてのインタラクティブ要素が機能する（フォーム、検索、フィルター、モーダル、ナビゲーション）
• クリーンな状態から bash /workspace/start.sh が動作する
• http://localhost:3000 からアプリにアクセスできる
• 設計ドキュメントが完成している
• デプロイ手順を記載した README がある

重要な原則

1. プロトタイプを正とする — PRD のテキストとプロトタイプ画像に食い違いがある場合、ビジュアルやレイアウトの判断ではプロトタイプを優先します。

2. データに関する近道はしない — プロトタイプに表示されるすべてのコンテンツは、API 経由でデータベースから取得する必要があります。フロントエンドコンポーネントにデータをハードコードしないでください。

3. 完全に実装する — すべてのページ、機能、操作を実装します。「細かな」機能も省略しないでください。別々のページを1つにまとめないでください。

4. リソースを使用する — プロトタイプに画像が表示され、対応するファイルが /workspace/resources/ にある場合は、そのファイルを使用します。プレースホルダー URL で代用しないでください。

5. 再現性を確保する — start.sh は、まったく何もない状態から実行できる必要があります。Node 18 以上が必要な場合は、Node 18 以上をインストールします。PostgreSQL が必要な場合は、PostgreSQL をセットアップします。

6. 思い込みではなく検証する — ビジュアル検証ループ（Phase 5）を使って、出力とプロトタイプを実際に比較します。API チェックでエンドポイントを検証します。start.sh を実行して、デプロイを検証します。