目的

固定スタックの個人開発 SaaS を、ブレない設計と実装ルールで立ち上げる。
技術説明ではなく、実装時の行動基準とプロジェクト構造を強制するための Skill。

使用タイミング

• Next.js + FastAPI 境界を持つ SaaS を新規に作るとき
• 固定スタックで要件定義から scaffold まで一貫して進めたいとき
• Gemini CLI を使って docs・設計・実装計画を高速化したいとき
• 個人開発向けに現実的で保守しやすい構成を最初から敷きたいとき

使用しないタイミング

• 技術選定を自由に変えたいとき
• Python が主役のバックエンドを作るとき
• 単なる小規模 LP や静的サイトだけを作るとき
• この固定 stack を外す予定が強いとき

プロジェクト前提条件

• Frontend は Next.js App Router
• UI は Tailwind + shadcn/ui
• DB は Neon PostgreSQL
• ORM は Prisma 6
• Auth は Clerk
• Email は Resend
• Payments は Stripe
• Storage は Cloudflare R2
• Analytics は PostHog
• Error Monitoring は Sentry
• Deploy は Vercel
• FastAPI は Python-required workloads のみ

ルール

• docs を先に作り、実装を後追いさせる
• GEMINI.md に source of truth を明記する
• Next.js をデフォルト backend とし、FastAPI を乱用しない
• Clerk auth を Prisma に複製しない
• Stripe 成功判定は webhook 起点にする
• R2 にファイル本体を保存し、DB には metadata だけを置く
• 各 project-level skill は共通テンプレートの型にそろえる
• 各 skill は技術説明ではなく実装時の行動規範として書く
• Prisma は 6 系を固定で使う。7 系へ勝手に上げない
• 開発 DB はローカル可だが、本番 DB は Neon PostgreSQL を前提にする

ワークフロー

1. product goal と MVP を整理する
2. references/project-bootstrap-checklist.md を確認する
3. scripts/bootstrap_tree.sh で理想構成を作る
4. scripts/generate_gemini_md.sh で GEMINI.md を作る
5. scripts/generate_project_docs.sh で docs を生成する
6. docs を source of truth にして実装へ進む
7. project-level skills を必要に応じて補強する

チェックリスト

• GEMINI.md があるか
• docs/requirements.md から docs/db-schema.md まで揃っているか
• skills/*/SKILL.md が共通テンプレートに沿っているか
• FastAPI を使う理由が説明できるか
• Stripe / Clerk / R2 の危険なアンチパターンを避けているか
• Vercel deploy 前提の env 設計が見えているか
• Prisma 6 を固定しているか
• 本番 DB が Neon を前提に設計されているか

よくある落とし穴

• Next.js で足りる処理まで FastAPI に逃がす
• docs を雑に作って source of truth が死ぬ
• skill を技術メモ化して、行動基準として使えなくする
• Clerk と Prisma の役割を混ぜる
• Stripe webhook を軽視して success redirect に依存する
• file upload を DB 中心で考える
• Prisma 7 に上げて接続・設定周りでハマる

期待される出力

• GEMINI.md
• docs 一式
• 理想ディレクトリ構成
• project-level skills 一式
• stack に沿った実装 plan または scaffold
• 必要なら GitHub / Vercel まで進めるための準備状態

source of truth の優先順位

プロジェクトファイルを生成・更新する際は、以下の順序で source of truth とみなす：

1. docs/requirements.md
2. docs/scope.md
3. docs/architecture.md
4. docs/conventions.md
5. docs/decisions/*.md
6. docs/notes/brainstorming.md は参照専用

固定スタック方針

• Frontend: Next.js App Router
• UI: Tailwind + shadcn/ui
• DB: Neon PostgreSQL
• ORM: Prisma 6
• Auth: Clerk
• Email: Resend
• Payments: Stripe
• Storage: Cloudflare R2
• Analytics: PostHog
• Error Monitoring: Sentry
• Deploy: Vercel
• Backend: FastAPI only for Python-required workloads

バックエンド境界

デフォルトのバックエンドロジックは Next.js の route handlers または server actions に配置する。
FastAPI は AI 処理、バッチジョブ、重い計算処理、あるいは Python 特有の連携が必要な場合にのみ利用する。

絶対にやってはいけないこと

• Clerk auth state を完全な認証システムとして Prisma に複製しない
• Stripe の success redirect を source of truth と見なさず、webhook の状態を信頼する
• アップロードされたファイルを PostgreSQL に格納しない
• 明示的に必要でない限り、シンプルな CRUD のために FastAPI エンドポイントを追加しない
• デフォルトで Prisma 7 へアップグレードしない

対象プロジェクト構造

以下の構造を生成・整えることを目指す：

my-saas/
├─ GEMINI.md
├─ src/
│ ├─ app/
│ ├─ components/
│ ├─ features/
│ ├─ lib/
│ ├─ server/
│ ├─ hooks/
│ └─ types/
├─ backend/
│ └─ fastapi/
│ ├─ app/
│ ├─ tests/
│ └─ pyproject.toml
├─ prisma/
│ ├─ schema.prisma
│ ├─ migrations/
│ └─ seed.ts
├─ public/
├─ tests/
│ ├─ unit/
│ ├─ integration/
│ └─ e2e/
├─ docs/
│ ├─ requirements.md
│ ├─ scope.md
│ ├─ architecture.md
│ ├─ conventions.md
│ ├─ integrations.md
│ ├─ db-schema.md
│ ├─ decisions/
│ └─ notes/
│   └─ brainstorming.md
├─ .gemini/
│ └─ commands/
├─ skills/
│ ├─ nextjs/SKILL.md
│ ├─ clerk/SKILL.md
│ ├─ prisma/SKILL.md
│ ├─ shadcn/SKILL.md
│ ├─ stripe/SKILL.md
│ ├─ resend/SKILL.md
│ ├─ posthog/SKILL.md
│ ├─ sentry/SKILL.md
│ ├─ r2/SKILL.md
│ ├─ fastapi/SKILL.md
│ ├─ api-security/SKILL.md
│ └─ vercel/SKILL.md
└─ scripts/

この Skill が生成すべきもの

新規プロジェクトでは、少なくとも以下を生成することを目標とする：

• GEMINI.md
• docs/requirements.md
• docs/scope.md
• docs/architecture.md
• docs/conventions.md
• docs/integrations.md
• docs/db-schema.md
• docs/notes/brainstorming.md
• prisma/schema.prisma
• src/ 下の基本アプリ構造
• backend/fastapi/ 下の基本 FastAPI 構造
• .env.example
• Clerk、Stripe、Resend、PostHog、Sentry、R2 各サービスの統合または実装計画

参考資料

必要に応じて参照：

• references/doc-templates.md
• references/integration-rules.md
• references/project-bootstrap-checklist.md
• references/project-skill-template.md

公開準備状況の備考

この Skill は、Gemini CLI と OpenClaw のファイル・シェル制御機能、およびオプションで ACP を併用した大規模実装ループにおいて最も効果を発揮する。
プロジェクトレベルの skills/*/SKILL.md ファイルは、汎用的なフレームワーク解説ではなく、実装ポリシーとして運用すべきである。

本 Skill を実際のプロジェクトで使用・公開する前に、以下の点を確認すること：

• Gemini CLI がインストールされ、認証済みであること
• 生成された skills/*/SKILL.md ファイルが共有テンプレートの形式に則っていること
• 主要な実装を開始する前に、プロジェクトの docs が生成済みであること
• FastAPI は Python が実際に必要な場合にのみ導入すること
• デプロイに関する想定が、対象プロジェクトにおける Vercel の実情と一致していること
• Prisma が 6.x に固定されていること
• 本番 DB の想定が、Neon の実情と一致していること