create-next-project

Next.js プロジェクトの作成

フルスタックの Next.js プロジェクトをガイドに沿ってスキャフォールディングします。エージェントチームによる並列実行を活用し、本番環境に対応したアプリをスキャフォールディング、設定、デプロイするための 6 つの対話型ステップです。

コアスタック（常に含まれます）

• Next.js（最新）と App Router、TypeScript、Tailwind v4、src/ ディレクトリ
• Bun をパッケージマネージャーおよびランタイムとして使用
• Biome によるリントとフォーマット（スキャフォールディング後に手動でインストール）
• アプリのシェルとして dashboard-01 ブロックを使う shadcn/ui
• テーマのカスタマイズ用の tweakcn（tweakcn.com の Web エディター）
• ライト／ダークモード用の next-themes
• 認証用の better-auth
• デプロイ用の Vercel

データレイヤー（データベースの選択によって異なります）

• Convex を選択した場合：クライアントデータには Convex 組み込みの useQuery／useMutation を使用します。TanStack Query は不要です。
• その他すべてのデータベース：クライアント側のデータフェッチ用に TanStack Query をインストールします。

---

ステップ 0：スキルを読み込む

作業を始める前に、次のスキルを呼び出してガイダンスをコンテキストに読み込んでください。

1. Skill(vercel-react-best-practices) - React／Next.js の最適化ルール
2. Skill(vercel-composition-patterns) - コンポーネントのコンポジションパターン
3. Skill(better-auth-best-practices) - 認証の統合パターン

すべてのステップで、これらのガイダンスを適用してください。

---

ステップ 1：スキャフォールディング + Git + リポジトリ

このステップでは、プロジェクトの基本構成をディスク上に作成し、バージョン管理に追加します。

1a. スキャフォールディング

対象ディレクトリにファイル（例：.claude/ ディレクトリ）がすでにある場合は、まず /tmp に移動してからスキャフォールディングを行い、その後ファイルを元に戻してください。

create-next-app には --biome フラグが追加されています（対話型プロンプトで「使用するリンターを選択してください：ESLint／Biome／なし」と尋ねられます）。ESLint でスキャフォールディングして後から削除するのではなく、このフラグを直接渡してください。

bunx create-next-app@latest <project-name> \
  --typescript --tailwind --app --src-dir \
  --import-alias "@/*" --use-bun --turbopack --biome --yes
cd <project-name>

1b. biome.json をプロジェクト標準の設定に合わせる

生成された biome.json は適切なデフォルト設定ですが、プロジェクト標準の設定で上書きしてください。正確な JSON と Biome 2.x のルールの完全な差異一覧（organizeImports の場所、files.ignore がないこと、フォルダーの無視構文、css.parser.tailwindDirectives）については、references/stack-defaults.md を参照してください。

package.json のスクリプトを更新します。

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "biome check .",
    "lint:fix": "biome check --write ."
  }
}

すべてのファイルを自動修正します。

bunx biome check --write .

1c. Git の初期化と確認

git init
bun run build
bun run lint
git add .
git commit -m "Initial Next.js scaffold with Biome"

1d. リポジトリについて確認する

次の 3 つの選択肢をユーザーに提示します。

1. 新しい GitHub リポジトリを作成する — gh org list で利用可能な組織を一覧表示し、どの組織を使うかユーザーに尋ねてから、gh repo create <org>/<name> --private --source=. --remote=origin を実行します（まだプッシュしないでください）。会話から組織名を推測してはいけません。必ず確認してください。
2. 既存のリモートを使用する — リモート URL を尋ねてから、git remote add origin <url> を実行します（まだプッシュしないでください）。
3. 今回はスキップする — リモートを設定せずに続行します。

重要：まだ GitHub にプッシュしないでください。 プッシュすると Vercel のデプロイが開始されますが、データベースがプロビジョニングされていない場合、デプロイは失敗します。最初のプッシュは、すべてのインフラストラクチャを設定した後のステップ 6 で行います。

---

ステップ 2：プロジェクトに関する質問をすべて確認する

スキャフォールディングが完了したので、必要な要件をすべて一度に確認します。複数の質問をまとめて AskUserQuestion を使用してください。

確認する項目：

1. 認証方法（複数選択可）：

   • メールアドレス／パスワード（推奨のデフォルト）
   • OAuth プロバイダー（Google、GitHub、Apple）
   • Sigma／Bitcoin 認証（BSV 対応アプリ）
   • パスキー／WebAuthn

2. データベース：

   • Convex（リアルタイム、サーバーレス） -- 注：TanStack Query を Convex 独自のクライアントに置き換えます
   • Turso/libSQL（エッジ SQLite）
   • PostgreSQL（従来型）
   • SQLite（ローカル開発）

3. オプションのパッケージ（複数選択可）：

   • @ai-sdk/openai + ai - AI／エージェント機能
   • @bsv/sdk - BSV ブロックチェーン
   • @1sat-lexi/js - 1Sat Ordinals
   • @1sat/connect + @1sat/react - 1Sat ウォレット連携
   • clawnet - ClawNet エージェントプラットフォーム
   • resend - トランザクションメール
   • なし

4. テーマ：「プリセット（nova、vega、maia、lyra、mira）を選ぶか、ui.shadcn.com/create でカスタムテーマを作成するか、tweakcn.com でテーマを選んでレジストリ URL を貼り付けてください。」

5. CLAUDE.md で参照するスキル（インストール済みプラグインから複数選択可）：

   • 利用可能なスキルを一覧表示します
   • vercel-react-best-practices と vercel-composition-patterns は必ず含めます

回答はすべて記録してください。これらは調査エージェントとビルドチームに共有されます。

---

ステップ 3：調査エージェントを割り当てる

ビルド作業の各領域についてコンテキストを収集するため、並行して調査エージェントを実行します（Agent ツールを run_in_background: true で使用）。各エージェントは関連するソースコード、ドキュメント、またはスキルを読み込み、ビルドエージェントが必要な情報をすべて得られるようにします。

エージェントの割り当て（同時に実行）：

調査エージェント 1：UI + レイアウト

• references/layout-architecture.md と references/stack-defaults.md を読み込みます
• ユーザーが tweakcn URL を指定した場合は、ビルドエージェントにその情報を伝えます
• プロジェクトに固有のレイアウト要件（Discord のようなレイアウト、ダッシュボードなど）がある場合は、そのパターンを調査します

調査エージェント 2：認証

• references/auth-setup.md を読み込みます
• ユーザーの選択に応じて、関連する認証スキルを呼び出します：
  • Sigma：Skill(sigma-auth:setup-convex) または Skill(sigma-auth:setup-nextjs)
  • パスキー：better-auth のパスキーに関するドキュメントを読み込みます
  • OAuth：プロバイダーごとに必要な環境変数を記録します
• Convex を使用する場合は、@convex-dev/better-auth アダプターパターンを調査します

調査エージェント 3：データ層

• Convex の場合：Skill(convex-best-practices) を呼び出し、Convex のスキーマパターンを読み込みます
• Turso／PostgreSQL／SQLite の場合：references/tanstack-query-setup.md を読み込みます
• プロジェクトに既存のデータモデルがある場合、または移植元の旧プロジェクトがある場合は、それらのソースファイルを読み込みます
• データ層で必要となる環境変数をすべて特定します

調査エージェント 4：オプションのパッケージ（ユーザーがパッケージを選択した場合のみ）

• 選択された各パッケージの設定要件を調査します
• 環境変数、プロバイダーの設定、連携パターンを特定します

ステップ 4 に進む前に、すべての調査エージェントの完了を待ちます。

---

ステップ 4：ビルドチームを編成する

専門エージェントで構成されるエージェントチームを作成します（TeamCreate を使用）。ステップ 2 の回答とステップ 3 の調査結果から得たコンテキストを、各エージェントにすべて提供します。

チーム構成：

• エージェント 1：UI + レイアウト + テーマ（フェーズ 2～3） -- shadcn の初期化、dashboard-01 ブロック、テーマプロバイダー、単一レイアウトへの再構成
• エージェント 2：データ層（フェーズ 4） -- データベースの選択に応じて Convex または TanStack Query を設定
• エージェント 3：認証（フェーズ 5、エージェント 2 の完了後に開始） -- better-auth のサーバー／クライアント設定、ログイン／サインアップページ、ミドルウェア
• エージェント 4：設定 + オプションのパッケージ（フェーズ 6～7、他のすべてのエージェントの完了後に開始） -- オプションのパッケージ、.claude/CLAUDE.md、.env.vercel、最終的なビルド／lint チェック

エージェントの調整：

• エージェント 1（UI）とエージェント 2（データ）は並行して実行できます
• エージェント 3（認証）はエージェント 2 の完了を待つ必要があります（データレイヤーのスタブ／設定が必要です）
• エージェント 4（設定）は他のすべてのエージェントの完了後に実行します（すべての環境変数を把握する必要があります）

すべてのエージェントに、プロジェクトのパス、ステップ 2 の回答、関連するステップ 3 の調査結果、必要な参照ファイルの内容、Biome 2.x のルール（非 null アサーションを使用しないなど）、およびコミット前に bun run build と bun run lint を実行する手順と、内容がわかるコミットメッセージを付ける指示を必ず渡してください。

各エージェントのコマンドごとの担当範囲の詳細は、references/build-team.md を参照してください。

---

ステップ 5：Vercel でデータベースをプロビジョニングする

すべてのエージェントの作業が完了し、ローカルでビルドが成功したら、初回デプロイの前にデータベースをプロビジョニングします。データベースなしでデプロイすると、デプロイが機能しなくなり、データベースの重複や接続の切れたインスタンスが作成される可能性があります。

ここでは人間の介在が必要です。ユーザー自身が Vercel プロジェクトを作成し、ストレージを追加します（エージェントは Vercel プロジェクトを作成してはいけません）。次に、vercel link でローカルプロジェクトをリンクし、vercel env pull で環境変数を取得してから、データベース固有の設定を完了します。Convex では Vercel Marketplace のインテグレーションを通じて 4 ステップのガイドに従う必要がありますが、Turso／PostgreSQL／SQLite は CLI またはダッシュボードで簡単に設定できます。

詳しい手順（Vercel プロジェクトとストレージの設定、リンク、環境変数の取得、Convex／Turso／PostgreSQL／SQLite ごとの設定）、Convex の _generated/ スタブファイル、Convex 固有の注意点の一覧については、references/database-provisioning.md を参照してください。

---

ステップ 6：初回デプロイと継続的なワークフロー

データベースのプロビジョニングと環境変数の設定が済んだら、プッシュして初回デプロイを開始します。

git push -u origin main

または、ユーザーがまだ GitHub リモートを設定していない場合は、gh org list で組織の一覧を表示してユーザーに選択してもらい、その後 gh repo create <org>/<name> --private --source=. --remote=origin --push を実行します。

継続的な開発では、2 つのターミナルを使用します。bunx convex dev（Convex を使用する場合。開発環境のデプロイ先にプッシュします）と、bun dev（Next.js。.env.local を介して開発環境の Convex に接続します）を並行して実行します。本番環境は、Vercel のビルド中に convex deploy を実行して本番環境の Convex デプロイ先に接続します。開発環境と本番環境では、データ、環境変数、関数コードがそれぞれ分離されています。

デプロイ後は、クライアントエラーなしでアプリが読み込まれること、認証が機能すること、テーマ切り替えが機能することを確認します。Skill(react-doctor) と bun run lint を実行し、指摘された問題をすべて修正してください。新規プロジェクトなら、単に「合格」するだけでなく、スコア 100 を目指してください。

初回デプロイの全手順、2 ターミナルでの開発ワークフロー、開発環境と本番環境の比較表、検証チェックリストの全項目、.env.vercel ファイルのパターン（ステップ 1／4 で作成し、プロジェクトに必要なすべての環境変数を記載して、.gitignore の例外としてリポジトリにコミットする）については、references/deployment-workflow.md を参照してください。

---

主な原則

• どこでも Bun を使用 -- npm、npx、yarn は使用しないでください。すべてに bun、bunx を使用します
• --biome を直接指定してスキャフォールドする -- create-next-app に --biome フラグが追加されています。スキャフォールド時に指定し、後から ESLint を削除する方法は避けてください。それでも、生成された biome.json はプロジェクト標準の設定で上書きします
• Biome 2.x の設定 -- assist.actions.source.organizeImports、files.includes の否定パターン（files.ignore は使用しない）、css.parser.tailwindDirectives: true
• react-doctor のスコアを 100 にする -- プロジェクトを完了とする前に Skill(react-doctor) を実行してください。新規プロジェクトでスコアが 100 未満になる理由はありません
• 非 null アサーションは使用しない -- Biome は process.env.FOO! に警告を出します。必ず環境変数を検証し、分かりやすいメッセージを付けてエラーをスローしてください：

  // WRONG
  const url = process.env.DATABASE_URL!;
  // RIGHT
  const url = process.env.DATABASE_URL;
  if (!url) throw new Error("DATABASE_URL environment variable is required");
  

• ハンドラーの初期化は遅延させる -- 環境変数に依存する認証ルートハンドラーは、モジュール評価時ではなくリクエスト時に初期化する必要があります
• cron アクションには明示的な戻り値の型を指定する -- 循環型参照を回避できます
• Convex を使用する場合、TanStack Query の代わりに Convex を使う -- Convex を使用する場合は、convex/react の useQuery／useMutation を使用してください。TanStack Query はインストールしないでください。
• まず CLI を使う -- create-next-app、shadcn、biome、vercel、gh の CLI を使用します
• shadcn v4 の安全フラグ -- コンポーネントの追加を繰り返し調整するときは、適用前に変更をプレビューするため --dry-run と --diff を使用します
• 最新バージョンを使用する -- すべてのインストールで常に @latest を指定します
• ビルドを検証する -- コミットのチェックポイントごとに bun run build を実行します
• データベース構築前にプッシュしない -- Vercel Storage でデータベースを構築する前に、GitHub へプッシュしてはいけません。プッシュすると Vercel のデプロイが開始され、データベースが接続されていないため失敗します。その結果、デプロイが壊れたり、接続されていない重複データベースインスタンスが作成されたりする可能性があります
• エージェントチーム -- Claude Code では TeamCreate を使用してフェーズ 2～7 を並行して進めます。各エージェントには会話履歴がないため、十分なコンテキストを提供してください。

追加リソース

参考ファイル

• references/stack-defaults.md -- Biome、テーマプロバイダー、Tailwind、shadcn/ui を設定する際に読みます。正確な設定、プリセット、安全フラグが記載されています
• references/layout-architecture.md -- dashboard-01 ブロックを単一レイアウトのパターン（ナビバー／サイドバーのシェル＋ルートコンテンツ）に再構成する際に読みます
• references/auth-setup.md -- 認証方式（メール／パスワード、OAuth、Sigma、パスキー）またはデータベースアダプターで better-auth を接続する際に読みます
• references/tanstack-query-setup.md -- Convex を使用しないプロジェクトでデータレイヤー（プロバイダー、カスタムフック）を設定する際に読みます
• references/build-team.md -- ステップ 4 のビルドチームを割り当てる前に読みます。各エージェントのコマンドごとの具体的な役割と、コンテキストのチェックリストが記載されています
• references/database-provisioning.md -- ステップ 5 で読みます。Vercel とデータベース（Convex、Turso、PostgreSQL、SQLite）の構築手順、Convex の _generated/ スタブ、Convex の注意点が記載されています
• references/deployment-workflow.md -- ステップ 6 で読みます。初回デプロイの手順、継続的な開発ワークフロー、開発環境と本番環境の比較表、検証チェックリスト、.env.vercel パターンが記載されています

関連スキル

• vercel-react-best-practices -- React／Next.js の最適化ルール
• vercel-composition-patterns -- スケーラブルなアプリのためのコンポーネント構成
• frontend-design -- ありきたりなデザインを避ける UI デザイン
• better-auth-best-practices -- 認証統合のパターン
• convex-best-practices -- Convex のパターン（Convex を使用する場合）
• sigma-auth:setup-convex -- Convex での Sigma 認証
• sigma-auth:setup-nextjs -- Next.js での Sigma 認証（Convex を使用しない場合）