jayabdulraman/setup-prototype-project

プロトタイププロジェクトのセットアップ

アイデアから動作するWebアプリを構築し、ライブリンクとして共有します。ユーザーは方向性と判断を提供し、あなたは技術作業を行います。

スタック

レイヤー	デフォルトツール
インターフェース（ユーザーが見たりクリックしたりするもの）	Next.js（App Router）+ TypeScript + Tailwind + shadcn/ui（ベースUI、ニュートラルテーマ、Lucideアイコン、Seraスタイル）を1つのshadcnプリセットから
サーバー処理（秘密鍵、外部API、AI呼び出し）	Next.js Server Actions
データ	ブラウザ内IndexedDB（Dexie）。後で使うためにSupabase CLIをインストール
ホスティングと共有	Vercel
セットアップと自動化	公式CLI（vercel、supabase、gh、shadcn）+ このスキルのスクリプト

IndexedDBを最初に使用：アカウント不要、キー不要、オフラインでも動作。データを複数のユーザーやデバイスで共有する必要がある場合、アプリにログインが必要な場合、またはサーバー/スケジュールジョブがデータを読み取る必要がある場合にのみSupabaseに移行します（references/7-extend.mdを参照）。

常に最新の安定版リリースを使用（確認不要）

• アップグレードは承認不要ですが、1つの例外があります：サードパーティのHomebrew tap（例：supabase/tap）から提供されるツールです。そのようなtapを信頼する前、およびセットアップ中にそのtapからアップグレードする前に確認してください（以前承認されていても行います）。
• それ以外の場合は、すべてのCLIとパッケージを最新の安定版にアップグレードします：npm i -g <cli>@latest、brew upgrade、winget upgrade、Node.jsの現在のLTS、およびプロジェクト内でnpm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i。アップグレードした内容を1行で伝えてください。
• ユーザーが明示的に要求しない限り、canary、beta、rc、nextタグは使用しないでください。バージョンを記憶やこれらのドキュメントから固定しないでください。
• アップグレード後、チェック（lint、typecheck、build）を実行します。いずれかが失敗した場合、エラーを読んで壊れたパッケージを特定し、そのパッケージのみを前のメジャーバージョンの最新リリースにダウングレードし（npm i -D <pkg>@^<major-1>）、再実行します。固定理由をPROTOTYPE.mdの「決定」に記録します。例：TypeScript 7がESLintのTypeScriptプラグインを壊したため、typescript@^6を固定し、それ以外は最新を維持します。
• 既存のプロトタイプを再開する場合も、新しい作業の前に同じアップグレード＆チェックパスを実行します。

構築の手順

各ステップに達したら、その参照ファイルを読んでください。事前にすべてを読まないでください。

ステップ	ユーザーの作業	あなたの作業	参照
1. セットアップ	フォルダを選択	ツールとその依存関係をチェック、不足分をインストール、アプリをスキャフォールド	references/1-setup.md
2. 接続	承認、ブラウザで1回サインイン	各CLIのログインを実行、動作確認、アプリキーをOSの資格情報ストアに保存	references/2-connect.md
3. 仕様	アイデアを具体化	短い質問ラウンドを実施、SPEC.mdを作成	references/3-spec.md
4. 構築	反応、方向修正	一度に1つの機能を構築、動作を表示	references/4-build.md
5. テスト	試用	チェックを実行、実際のブラウザでテスト、修正	references/5-test.md
6. 出荷	承認、共有	Vercelにキーを同期、デプロイ、リンクを提供	references/6-ship.md
いつでも	新しい機能を要求	ツールのCLIまたはスキルを見つけ、インストールと接続を依頼	references/7-extend.md

結果：localhostで動作するアプリ、次に誰でも開けるライブリンク。

プラットフォーム

	macOS	Windows	Linux
このスキルのスクリプト用シェル	ターミナル（zsh/bash）	Git Bash（Git for Windowsに付属）	bash
CLI用パッケージマネージャー	Homebrew	winget（SupabaseはScoop）	Linux用Homebrew、またはnpm
アプリキーの保存場所	キーチェーン	資格情報マネージャー	Secret Service（secret-tool）。それ以外はgit無視の.env.local

• スクリプトはbash <絶対パス>で実行します。WindowsのPowerShellまたはcmdからは、bashがWSLを起動する可能性があるため、代わりに& "$env:ProgramFiles\Git\bin\bash.exe" <script>を使用します。Claude Code on WindowsはすでにシェルをGit Bashで実行しています。
• WSLはLinuxとしてカウントされますが、secrets.shは到達可能な場合、PowerShellを使用してWindows資格情報マネージャーを利用します。
• クラウド同期フォルダ（Dropbox、OneDrive、iCloud、Google Drive）でも問題ありません。Dropboxフォルダ内では、スキャフォールディング直後にbash SKILL/scripts/ignore-sync.sh <project>を実行し、Dropboxがnode_modules、.next、テスト出力をスキップするようにします。

進捗ファイル

すべてのプロトタイプのルートにPROTOTYPE.mdがあります（テンプレート：templates/PROTOTYPE.md）。これにはステップのチェックリスト、ツール一覧（ツール、バージョン、グローバルまたはプロジェクトインストール）、キーの名前（値は不可）、決定事項、リンクが含まれます。

• 各ステップの終了時とツールが追加されるたびに更新します。
• 既存のプロトタイプ内で呼び出された場合、最初にPROTOTYPE.mdを読み、最初の未チェックステップから再開します。ユーザーが特定のステップを指定した場合（「出荷しよう」）、そこに移動しますが、そのステップのチェックを最初に実行します。
• すべてのステップがチェックされ、ユーザーが新しい機能を希望する場合：それをSPEC.md（必須機能＋受け入れチェック）およびPROTOTYPE.mdの「機能」に追加し、新しいツールが必要な場合はreferences/7-extend.mdを実行し、その機能について構築→テスト→出荷のループを繰り返します。

すべてのコマンドを自分で実行する

ユーザーは方向性と承認を提供します。すべてのコマンドは自分で実行します。ユーザーにコマンドを入力または貼り付けさせることは決してしないでください。

• 承認不要：情報の調査、アップグレード（上記参照）、デフォルトスタックとその依存関係のインストール（ユーザーがプロトタイプを依頼した場合）。インストールする内容と理由を1行で伝え、実行します。
• 最初に確認（1つの平文で理由を説明し、承認されたら自分で実行。1つの承認で一連の処理をカバーできます）：
  • CLIへのサインイン
  • セキュリティ設定の変更（例：Homebrew tapの信頼brew trust supabase/tap、およびサードパーティtapからのツールアップグレード）
  • デフォルトスタック以外のツールのインストール（references/7-extend.md）
  • クラウドリソースの作成（Vercelプロジェクト、Supabaseプロジェクト、GitHubリポジトリ、マーケットプレイス統合）
  • 本番環境へのデプロイ
  • 仕様の確定と「仕様」から「構築」への移行
• ユーザーのリクエストがすでに「ライブリンクまで持っていく」と明示している場合、それがVercelプロジェクトと本番デプロイの承認となります。それでも、実行前に何を行おうとしているかを1行で伝えてください。

コマンドにユーザーの操作が必要な場合（ブラウザサインイン、確認コード、管理者パスワード）：

1. 何が起こり、ユーザーが何を見るかを説明します。
2. ユーザーが見て応答できる場所で実行します：エージェントアプリのターミナルパネル（「ターミナルで実行」ツール）があればそれを使用します。各サインインに新しいタブを作成し、そのタブに名前を付けます（「Vercelサインイン」、「GitHubサインイン」）。他の目的のタブを再利用しないでください。ターミナルパネルをそのタブにフォーカスし（「ペインを表示」ツール）、メッセージでタブにリンクします。パネルがない場合、ユーザー用にターミナルウィンドウを開きます（macOS：osascript -e 'tell application "Terminal" to do script "cd <project> && <command>"'、Windows：start "" "%ProgramFiles%\Git\git-bash.exe" -c "<command>; read"）。
3. ユーザーが「完了」と言うのを待ち、自分で確認します（vercel whoami、gh auth status...）。ユーザーの言葉だけでステップを完了としないでください。

シークレット（APIキー、トークン）は、次の優先順位で処理します：

1. 最優先：自動化：Vercel Marketplaceの統合（キーはVercelに配置され、secrets.sh pull-vercelで取得）、またはプロバイダーCLIのキー出力を直接secrets.sh set NAME --stdinにパイプ。ユーザーはキーを見たり貼り付けたりしません。
2. 最後の手段：ダイアログ：サービスが上記のいずれも提供しない場合のみ、bash SKILL/scripts/secrets.sh ask NAME "場所"を実行します。これにより、ユーザーの画面に非表示入力ダイアログが開き、値をOSの資格情報ストアに保存します。チャットや出力には何も表示されません。最初にユーザーにダイアログが表示されることと理由を伝えてください。 チャットでシークレットを要求したり、表示したり、コードやコミット対象ファイルに書き込んだりしないでください。

シェルの作業ディレクトリは呼び出し間でリセットされる可能性があります：すべてのプロジェクトコマンドをcd "<project>" &&で開始してください。長時間実行コマンド（npm run dev）はバックグラウンドで実行します。

ユーザーとの会話方法

• 各アクションの前に、そのアクションがユーザーに何をもたらすかを1つの平文で説明：「ブラウザデータベースを追加して、リストが訪問間で保存されるようにします。」
• 各ステップの後、2〜3行のまとめ：何ができるようになったか、何を試せるか、次は何か。
• 実際に選択肢がある場合は、2〜3のオプションと推奨を提示します。それ以外の場合は、適切なデフォルトを選択し、選択した内容を伝えます。
• 説明するよりも表示する：表示可能な変更のたびにlocalhostを開く（またはスクリーンショットを撮る）。
• エラー：まず自分で修正します。ユーザーを呼ぶのは、決定、承認、またはサインイン、パスワード、キーのための手が必要な場合のみです。

バンドルファイル

• scripts/preflight.sh [dir] — ツール、依存関係、インストール済みと最新バージョンの比較、ログイン、フォルダチェック
• scripts/secrets.sh — OS資格情報ストレージ（askは非表示入力ダイアログを開く）、キー付き実行、.env.localエクスポート、Vercelプッシュ/プル（使い方はhelp）
• scripts/ignore-sync.sh <project> — Dropboxにnode_modules、.next、テスト出力を同期しないように指示
• scripts/wincred.ps1 — secrets.shが使用するWindows資格情報マネージャーヘルパー（直接呼び出さない）
• scripts/discover.sh <tool> — 新しいツールのCLI、npmパッケージ、スキルの初期調査
• scripts/install.sh — このスキルをグローバルにインストール（プロジェクトレベルにフォールバック）
• templates/ — PROTOTYPE.md、SPEC.md、AGENTS.section.md、db.ts、actions.ts、smoke.spec.ts、playwright.config.ts

このドキュメント内のSKILLは、このスキルのフォルダ（例：~/.agents/skills/setup-prototype-project）を意味します。スクリプトを実行するときは絶対パスに展開します：bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh。

よくある間違い

間違い	代わりに
ユーザーにコマンドの実行や貼り付けを依頼する	説明し、承認を得て、自分で実行する（サインインは可視ターミナルで）。
ユーザーが言っただけでログイン完了とする	CLIで確認する（vercel whoami、gh auth status、supabase projects list）。
Dropboxにnode_modulesを同期させる	スキャフォールディング直後にignore-sync.shを実行する。
依存関係の前にCLIをインストールする	1-setup.mdのインストール順序に従う（パッケージマネージャー→git→Node.js→npm CLIs）。
記憶からインストールする（npm i next@15）	@latestの安定版を使用。チェックが失敗した場合のみ1つのパッケージをダウングレードする。
初日からSupabaseを使用する	IndexedDBから開始。共有やログインが必須になったらアップグレードする。
Server ComponentやServer ActionからIndexedDBを呼び出す	IndexedDBはブラウザ内のみに存在する。"use client"コンポーネントで使用する。
APIキーをNEXT_PUBLIC_変数に入れる	NEXT_PUBLIC_はすべての訪問者に公開される。キーはServer Actionsのサーバーサイドに保持する。
何も表示せずにすべての機能を構築する	一度に1つの機能を構築し、動作を表示してから反応する。
キーを同期せずにデプロイする	デプロイ前にsecrets.sh diff-vercelを実行する。
IndexedDBを読み取るジョブをスケジュールする	サーバージョブはブラウザデータを参照できない。最初にSupabaseにデータを移行する（7-extend.md）。
ログアウト状態で確認せずにリンクを渡す	共有前に本番URLが公開で200を返すことを確認する（6-ship.md）。
検索結果から誰が公開しているかを確認せずにツールをインストールする	ベンダーの公式CLI、パッケージ、またはスキルを優先する。確認時に公開元を表示する。