FastAPI x React Fullstack Template

開発者（人間）が ターミナルを触らず、Cursor上で 自然言語でAgentに依頼するだけ で開発できるフルスタックテンプレートです。

🎯 プロダクト構成

プラットフォーム	技術	デプロイ先
Web	React + Vite（レスポンシブ: PC/Tablet/Smartphone）	Vercel
iOS / Android	Capacitor	App Store / Google Play
デスクトップ	Electron	Windows / macOS

インフラ	サービス
バックエンドAPI	Railway
データベース	Postgres（Railway）
課金/決済	Stripe

---

TL;DR（最短の入口）

• 環境構築: .github/prompts/setup.prompt.md を使ってAgentに依頼（preflight実行）
• 実装を始める: .github/prompts/dev.prompt.md の入力テンプレだけ埋めて依頼
• 品質担保: pnpm quality-gate（Agentが実行）

---

🚀 初めての環境構築

Step 1: Cursorでプロンプトファイルをメンション

Cursorのチャット欄で以下のようにメンション（@ で補完）してください：

@.github/prompts/setup.prompt.md

Step 2: 依頼文を入力して送信

このリポジトリをローカルで動かせるように環境構築してください。

Step 3: Agentが自動で環境構築を実行

• 必要コマンドの検出（git/python/pnpm/uv/docker）
• 依存関係のインストール
• 品質ゲート（format/lint/typecheck/build）

---

前提条件

項目	必須	確認方法
Docker Desktop	✅	docker --version
Node.js (v20+)	✅	node --version
pnpm (v10+)	✅	pnpm --version
Python (3.11+)	✅	python --version
uv	✅	uv --version

---

プロジェクト構成

/
├── backend/           # バックエンドAPI（FastAPI + Postgres）→ Railway
├── frontend/          # フロント（React + Vite）→ Vercel / Capacitor / Electron
├── scripts/           # 品質ゲート / preflight
├── documents/         # Spec/テンプレ/設定SSOT
└── docker-compose.yml # 開発用（Postgres + API）

---

開発の入口

環境構築

正本プロンプト: .github/prompts/setup.prompt.md

実装〜PRまで

正本プロンプト: .github/prompts/dev.prompt.md

---

品質ゲート（必須）

• pnpm quality-gate（または pnpm qg）

---

よく使うURL（ローカル）

• フロント（Vite）: http://localhost:5173
• バックエンドAPI: http://localhost:8000
• API docs: http://localhost:8000/docs
• health: http://localhost:8000/health

---

デプロイ

フロントエンド（Vercel）

• GitHub リポジトリを Vercel に接続
• frontend/ をルートディレクトリに設定
• 環境変数 VITE_API_BASE_URL を本番APIに設定

バックエンド（Railway）

• GitHub リポジトリを Railway に接続
• backend/ をルートディレクトリに設定
• Postgres アドオンを追加
• 環境変数を設定（DB_*, STRIPE_* など）

---

ドキュメント

• documents/README.md
• documents/spec/ - 仕様SSOT
• documents/tech-stack.md - 技術スタック
• documents/setup/subprojects-setup.md - サブプロジェクト環境構築
• AGENTS.md - AI Agent向けガイド

---

🤖 サブプロジェクト（AI エージェント / 開発ツール）

サブプロジェクトは git submodule として vendor/ 配下で管理されています。

プロジェクト	説明	必要環境
vendor/browser-use	AI ブラウザ自動操作エージェント	Python 3.11+, uv
vendor/android-use	Android AI エージェント	Python 3.10+, ADB
vendor/react-grab	React コンポーネントコンテキストコピー	Node.js 18+, pnpm

サブモジュール初期化（初回のみ）

pnpm submodule:init

一括セットアップ

# 全サブプロジェクトをセットアップ
pnpm setup:subprojects

# 個別セットアップ
pnpm setup:browser-use
pnpm setup:android-use
pnpm setup:react-grab

browser-use

AI ブラウザエージェント。LLMでWebブラウザを自動操作。

pnpm setup:browser-use

使用例:

from browser_use import Agent, Browser, ChatBrowserUse
import asyncio

async def main():
    agent = Agent(
        task="GitHubでbrowser-useのスター数を調べて",
        llm=ChatBrowserUse(),
        browser=Browser(),
    )
    await agent.run()

asyncio.run(main())

android-use

Android AI エージェント。ADB経由でAndroidアプリを自動操作。

pnpm setup:android-use

使用例:

cd vendor/android-use
source .venv/bin/activate  # または .\.venv\Scripts\Activate.ps1
python kernel.py
# Enter your goal: 設定を開いてWi-Fiをオンにして

react-grab

React コンポーネントコンテキストコピーツール。⌘C / Ctrl+C でUI要素のコンポーネント情報をコピー。

pnpm setup:react-grab

プロジェクトに導入:

npx grab@latest init

詳細: documents/setup/subprojects-setup.md