create-agentic-app

Agentic App の作成

「何かを作りたい」という段階から、http://localhost:3000 で検証済みの実行中の Agentic Coding Starter Kit プロジェクトを作成するまで、ユーザーを案内します。各ステップには明確な目的があります。ユーザーにその都度、目的を簡潔に説明し、どのような判断が代わりに行われているのかを理解してもらいます。

以下のシェルコマンドはすべて POSIX 形式で記述されています。Windows では、すべての対応プラットフォームで利用可能な Bash ツール（Git Bash／WSL）から実行してください。コマンドで実際に問題が発生しない限り、PowerShell 用に書き換えないでください。

このスキルは、実際の分岐点が 2 つある直線的な手順です。フォルダー戦略（ステップ 2）とデータベースの選択（ステップ 6）です。それ以外は、はい／いいえの質問か既定値のどちらかです。ステップを順番に進めてください。先に進むと、後の前提が崩れます（例：マイグレーションには設定済みの POSTGRES_URL が必要です）。

<pm> の置き換え： このファイルおよび参照資料全体で、<pm> は選択したパッケージマネージャーのプレースホルダーです。次のように置き換えてください。

• pnpm → pnpm db:migrate、pnpm build:ci、pnpm dev
• npm → npm run db:migrate、npm run build:ci、npm run dev（npm のスクリプト実行には run が必要です）
• yarn → yarn db:migrate、yarn build:ci、yarn dev

1. 事前チェック

ユーザーに選択を求める前に、すでにインストールされているものを確認します。先に調べることで、後の質問では実際に利用できる選択肢だけを提示できます。pnpm がインストールされていないとわかった後に「pnpm と npm のどちらにしますか？」と尋ねるほど、無駄なことはありません。

Bash の呼び出しを 1 回にまとめ、6 つのチェックを並列で実行します。

node --version
pnpm --version
npm --version
yarn --version
docker --version
git --version

結果を次のように解釈します。

• Node.js は >= 18 である必要があります。node --version が失敗するか、18 未満のバージョンを返した場合は、そこで停止し、https://nodejs.org から Node 18 以降をインストールするようユーザーに伝えてください。以降のすべてのステップで Node が必要なため、続行しないでください。
• Git がインストールされている必要があります（スキャフォルダーで使用します）。見つからない場合は停止し、https://git-scm.com/downloads を案内してください。
• パッケージマネージャー：pnpm、npm、yarn のうち、どれが成功したかを記録します。失敗したものは除外してください。ステップ 3 で選択肢として提示してはいけません。
• Docker はここでは任意です。ステップ 6 でローカルデータベースを選ぶ場合にのみ必要です。docker --version が成功したかどうかを記録してください。

確認結果は、短い文 1 つでユーザーに伝えてください。例：「Node 20.11、pnpm 9.1、npm 10.5、Docker 27.0、Git 2.43 が見つかりました。Yarn は検出されませんでした。」コマンドの生の出力をそのまま表示しないでください。

2. フォルダー戦略

スキャフォルダー（create-agentic-app）は、空ではないターゲットへの書き込みを拒否します。現在の作業ディレクトリの状態に応じて、エージェントは適切な呼び出し方を選ぶ必要があります。

作業ディレクトリ内の内容を確認するため、ドットファイルも含めて ls -A を実行します。

2a. 空、または .git のみの作業ディレクトリ

ディレクトリが空、または .git しか含まれていない場合は、その場に直接スキャフォールドします。ステップ 3 に進みます。後で npx create-agentic-app@latest . を実行します。

2b. 空ではない cwd

AskUserQuestion を使って、ユーザーに次のように尋ねます。

「このフォルダーは空ではありません。スターターのひな形をどこに作成しますか？」

• サブフォルダー — 名前を選択します（デフォルト：my-app）。スターターは ./<name>/ に配置されます。
• このフォルダー — 一時ディレクトリにひな形を作成してから、ファイルを現在のフォルダーに戻します。スターターで現在のフォルダーの内容を置き換える場合（または既存の内容とマージする場合）は、こちらを使用してください。
• キャンセル — 中止して、まずディレクトリを整理します。

サブフォルダーを選んだ場合：フォルダー名を尋ねます。デフォルトは my-app です。ステップ 4 のひな形作成先は ./<name> にします。一時ディレクトリを使う手順は省略します。

このフォルダーを選んだ場合：隠しファイルや名前の衝突はいずれも問題になるため、エージェントは次の手順を慎重に実行します。

1. まだ存在しない一時ディレクトリ名を選びます：../$(basename "$PWD")-scaffold-tmp。そのパスがすでに使用されている場合は、短いランダムなサフィックスを追加します。
2. 一時ディレクトリでスキャフォールダーを実行します（ステップ 4 の <target> に一時ディレクトリを指定）。一時ディレクトリを使う場合は、必ず --skip-git を渡してください。渡さないと、CLI が一時ディレクトリ内に初回コミットを作成し、ファイルを戻す際に .git/ ディレクトリがユーザーの既存の .git/ を上書きして、履歴が失われます。
3. ひな形の作成が完了し、一時ディレクトリ内で実行可能な残りの手順（環境ファイル、マイグレーションなど。いずれも一時ディレクトリ内で実行できます）が完了したら、すべてのファイルを戻します。隠しファイルも含めるコマンドを使用してください。POSIX：

   shopt -s dotglob
   mv ../<temp-dir>/* ./
   shopt -u dotglob
   

   これにより、.env、.gitignore、.agents/、.claude/ や、スターターに含まれるその他のドットファイルもコピーされます。
4. 上書きする前に必ず：一時ディレクトリ内のファイルが cwd 内の既存ファイル（ユーザーがすでに持っている README.md、.gitignore、.git/ ディレクトリなど）と衝突する場合は、いったん停止して AskUserQuestion でどちらを残すかユーザーに尋ねます。ユーザーの作業を黙って上書きしてはいけません。
5. 移動後、空になった一時ディレクトリを削除します：rmdir ../<temp-dir>。

この処理を実行する前に計画をユーザーに説明し、cwd に何が起きるのか事前に知らせてください。

3. パッケージマネージャーの選択

AskUserQuestion を使って尋ねます。ただし、ステップ 1 の確認で正常に検出された選択肢のみを表示します。

「スターターで使用するパッケージマネージャーはどれですか？」

• pnpm (検出された場合のみ表示) — スターターで推奨されています。
• npm (検出された場合のみ表示)
• yarn (検出された場合のみ表示)
• こちらで選ぶ — エージェントに任せます。

ユーザーが「こちらで選ぶ」を選んだ場合は、インストールされているものの中から pnpm → npm → yarn の順に優先します。ステップ 1 で pnpm --version が失敗している場合は、ユーザーを困らせることになるため、希望に応えるためだけに pnpm を提案してはいけません。

以降のすべてのステップで、選択した <pm> を使用します。

4. スキャフォールドを実行する

npx create-agentic-app@latest <target> --package-manager <pm> --yes

一時ディレクトリを使う場合（ステップ 2b の「このフォルダー」）、上記のコマンドに --skip-git を追加します。理由についてはステップ 2b を参照してください。

<target> はステップ 2 で指定したパス（., ./my-app, または ../<temp-dir>）、<pm> は pnpm、npm、yarn のいずれかです（名前のみを指定し、--use- プレフィックスは付けません）。--yes フラグを指定すると、CLI の「ディレクトリが空ではありません」という確認プロンプトに自動で応答します。これを指定しない場合、CLI は対話形式でプロンプトを表示するため、Bash ツールでは処理が停止します。CLI が確認を求めるのは、<target> が名前付きの空でないディレクトリの場合のみです。<target> が . の場合、CLI は内容にかかわらず現在のフォルダーにそのまま書き込むため、ステップ 2 のフォルダー戦略が重要です。

スキャフォルダーの出力をユーザーに表示し、処理状況を確認できるようにしてください。CLI でエラーが発生した場合（レジストリのタイムアウト、権限の問題など）は、エラーメッセージをそのまま表示して停止してください。推測で復旧を試みないでください。スキャフォルダーのエラーの多くは、ユーザー側での修正（ネットワーク、npm の設定、権限）が必要です。

CLI は <pm> install と git init（--skip-git を指定した場合を除く）も自動的に実行します。重要：CLI は stdio: 'pipe' を使ってインストールの出力を取得するため、インストールに失敗しても警告が表示されるだけで、CLI の終了コードは 0 のままです。 続行する前に、依存関係が実際にインストールされたことを確認してください。

test -d <target>/node_modules && ls <target>/node_modules | head -n 5

node_modules/ が存在しないか、ほとんど空の場合は、先に <target> 内で <pm> install を実行してください。そうしないと、後で db:migrate が失敗し、原因が分かりにくい Cannot find module 'drizzle-kit' エラーが発生して、ユーザーの時間を無駄にすることになります。

スキャフォールドが完了したら、その後の手順ではスキャフォールドしたディレクトリ内にいることを前提とするため、そこへ cd してください。一時ディレクトリを使う場合は、ひとまず cd ../<temp-dir> してください。ステップ 7（マイグレーション後）の後にファイルを元のフォルダーへ戻し、再度 cd します。一時ディレクトリ内でマイグレーションを実行して問題ありません。.env はその場所にあります。

5. .env を設定する

スターターには適切なデフォルト値を設定した env.example が含まれていますが、シークレットは未設定です。.env を準備してください。

1. .env がまだ存在しない場合は、テンプレートをコピーします。

   cp env.example .env
   

2. 強力な BETTER_AUTH_SECRET を生成します（env.example に含まれる値はプレースホルダーです。一時的なローカル開発環境以外では、必ず置き換えてください）。

   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
   

   出力された値を .env の BETTER_AUTH_SECRET=<value> として記入します。
3. NEXT_PUBLIC_APP_URL=http://localhost:3000 が設定されていることを確認します（テンプレートにはすでに設定されています）。
4. 次の値は現時点では空欄のままにします。後の手順でユーザーが利用を選択した場合に設定します。
   • OPENROUTER_API_KEY（ステップ 8）
   • BLOB_READ_WRITE_TOKEN（ステップ 9b）
   • POLAR_WEBHOOK_SECRET / POLAR_ACCESS_TOKEN（ステップ 9b）

ユーザーには次のように伝えます。「新しい認証シークレットを設定して .env を準備しました。データベース URL とオプションのインテグレーションは次に設定します。」

6. データベースの設定

AskUserQuestion を使って質問します。

「どの PostgreSQL のセットアップを使いますか？」

• ローカル Docker（ステップ 1 で docker --version が成功した場合のみ表示）— ローカル開発におすすめです。付属の docker-compose.yml を使用します。
• Neon — クラウド上の無料サーバーレス Postgres（個人開発や小規模プロジェクトに適しています）。
• Vercel Postgres — いずれにしても Vercel へのデプロイを予定している場合に最適です。
• 独自のデータベースを使用する — すでに POSTGRES_URL をお持ちの場合に選択します。

ユーザーが選択したら、ここで references/database.md を読み、選択した分岐の手順に従います。このファイルには、それぞれの方法で必要となる正確なコマンド、想定される接続文字列の形式、検証手順が記載されています。詳細をここに転載しないでください。内容が古くなるうえ、このワークフローが煩雑になります。

選択した分岐の手順が完了すると、有効な POSTGRES_URL が .env に設定されています。マイグレーションに進みます。

7. マイグレーションを実行する

<pm> db:migrate

これにより、スターターにあらかじめ生成されているマイグレーションが適用され、Better Auth のテーブルが作成されます。ボイラープレートには生成済みのマイグレーションが含まれているため、ここでは <pm> db:generate を実行する必要はありません。このコマンドが必要になるのは、後でユーザーがスキーマを変更するときだけです。

マイグレーションが失敗した場合の近道として、<pm> db:push は絶対に実行しないでください。プロジェクトの AGENTS.md のルールにあるとおり、drizzle push はマイグレーション履歴を迂回し、復旧が困難な差分を生み出します。db:migrate が失敗した場合は、エラーの内容をそのままユーザーに伝えてください。原因はほとんどの場合、POSTGRES_URL の誤り、データベースに接続できないこと、または認証情報が古いことです。根本原因を修正してもらった後、再試行を提案してください。

8. AI 機能 — オプトイン

ユーザーに尋ねます。

「AI 機能を有効にしますか？ このスターターでは Vercel AI SDK と OpenRouter を設定しているため、コードを変更せずにモデルを切り替えられます。今回はスキップして、後から追加することもできます。」

はいの場合：

1. API キーを作成するため、ユーザーを https://openrouter.ai/settings/keys に案内します。
2. キーを貼り付けてもらい、.env に OPENROUTER_API_KEY=<key> を設定します。
3. デフォルトの OPENROUTER_MODEL="openai/gpt-5-mini" で問題ないか確認するか、https://openrouter.ai/models に掲載されている任意のモデルに変更できることを伝えます。

いいえの場合：OPENROUTER_API_KEY は空欄のままにします。/api/chat のチャットルートを呼び出すとエラーが返されますが、アプリの他の部分は問題なく動作します。後で驚かないよう、この点をユーザーに伝えてください。

9. 認証 — 設定せずに案内する

おおむね次のようにユーザーに伝えます。

このスターターでは、メールアドレスとパスワードによる認証がデフォルトで有効になっています。MVP にはこれで十分です。ソーシャルログイン（Google、GitHub など）を利用したい場合は、Better Auth で追加できますが、まずはメールアドレスとパスワードで始め、実際に必要になった段階で OAuth を追加することをおすすめします。

ユーザーが今すぐ OAuth を利用したい場合は、references/auth.md を読んでください。このファイルには Better Auth のプロバイダーに関するドキュメントへのリンクがあり、WebFetch で該当ページを取得するようエージェントに指示しています。また、新しいプロバイダーを追加しても、メールアドレスとパスワードによる認証は有効なままにするよう注意を促しています。それ以外の場合はスキップしてください。OAuth は後から簡単に追加でき、最初から追加すると手間が増えるだけです。

9b. 本番環境向けの追加機能 — オプトイン（複数選択を一度だけ）

AskUserQuestion（複数選択）で一度だけ尋ねます。

「今すぐ設定したい本番環境向けの連携機能はどれですか？ 該当するものをすべて選択してください。すべて選択せずにスキップして、セットアップをシンプルに保つこともできます。後から追加できます。」

• Vercel Blob を使ったファイルのアップロード
• Polar を使った決済
• トランザクションメール（Resend / Postmark / など）

ユーザーが何も選択しなかった場合は、この手順全体をスキップしてください。リファレンスファイルを読み込んではいけません。ユーザーが必要としていないドキュメントの読み込みは、コンテキストの割り当てを無駄にします。

ユーザーが選択した項目ごとに、references/production-extras.md の該当するセクションを読んで、手順を案内してください。このファイルには Blob、Polar+ngrok、メール用の独立したセクションがあるため、該当するものだけを参照してください。

10. ビルドを検証する

<pm> build:ci

<pm> build ではなく build:ci を使用してください。デフォルトの build スクリプトはマイグレーションも実行しますが、ステップ 7 ですでにマイグレーションを行っているためです。2 回実行しても問題はありませんが、時間がかかり、出力も増えます。

ビルドが失敗した場合は、エラーの内容をそのままユーザーに伝えてください。よくある原因は、環境変数の不足（.env を再確認してください）や、古い Node モジュールです（必要であれば、もう一度 <pm> install を実行してください）。「先に進めながら修正する」ことでビルドの失敗を取り繕ってはいけません。この段階のビルドエラーの多くは設定ミスを示しており、後で開発サーバーにも問題を引き起こします。

11. 開発サーバーを起動して確認する

開発サーバーをバックグラウンドで起動します。

<pm> dev

Bash ツールの run_in_background: true オプションを使って実行し、残りの確認を並行して進められるようにします。Bash ツールはすぐに戻ります。Next.js のコンパイルとポート 3000 へのバインドには数秒かかるため、すぐに curl を実行しないでください。接続拒否エラーが発生し、アプリが壊れていると誤って判断することになります。

次のいずれかの方法で、起動準備が整うまで待ちます。

• 推奨：Monitor ツールを使ってバックグラウンドプロセスを監視し、Ready in または Local: http://localhost:3000 を含む行が表示されるまで待ちます。これはポートがバインドされたことを示す、Next 独自のシグナルです。
• 代替方法：2 秒間隔で HTTP チェックを 5 回再試行します。接続拒否は「まだ準備中なので再試行」と見なし、HTTP レスポンスがあれば（500 でも）「サーバーは起動しているので、本文を確認する」と見なします。

次の 3 点を確認します。

1. プロセスがまだ稼働していること。 起動中にクラッシュした開発サーバーは応答しません。結論を出す前に、バックグラウンドプロセスの出力を確認してください。
2. http://localhost:3000 から HTTP 200 が返ること。 Bash ツールを使います。

   curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000
   

   curl が使えない Windows では、PowerShell ツールから次のコマンドを実行します：(Invoke-WebRequest -Uri http://localhost:3000 -UseBasicParsing).StatusCode。
3. 開発サーバーの stdout/stderr に致命的なエラーがないこと。バックグラウンド出力を確認し、スタックトレース、DB 接続拒否、環境変数不足の警告を探します。

次のいずれかに該当する場合は、よくある原因として説明してください。

• ポート 3000 がすでに使用中 — 別のプロセスがポートを使用しています。ユーザーに伝え、別のプロセスを終了するか、PORT=3001 <pm> dev を実行してください。
• データベース接続が拒否された — Docker コンテナが停止している、POSTGRES_URL が間違っている、またはホスト型 DB が一時停止しています。ステップ 6 を再確認してください。
• BETTER_AUTH_SECRET が未設定、または強度が不十分 — ステップ 5 を再確認し、再生成してください。

成功したと伝える前に、問題を修正してください。中途半端に動作するアプリより、正直にエラーを伝えるほうが適切です。

12. 成功を報告する

次の順番でユーザーに伝えます。

1. アプリが http://localhost:3000 で起動していること。
2. **.env の場所（絶対パス）**と、設定済みの連携と空欄の連携の概要を 1 行で示します。例：「認証シークレット設定済み、Postgres 設定済み（Docker）、OpenRouter 設定済み、Blob／Polar／メールは空欄」。
3. エージェントに貼り付けて実際のアプリの構築を始められる最初のプロンプト。次のテンプレートを使います（README と一致します）。

I am using the Agentic Coding Starter Kit. Treat the existing app as boilerplate that should be replaced by the product I describe.

Use the project instructions in AGENTS.md or CLAUDE.md. During planning, ask clarifying questions before making assumptions. During implementation, split the work into small chunks, use sub-agents where useful, follow DESIGN.md for UI, preserve the existing tech stack unless there is a good reason to change it, and run lint, typecheck, and build before finishing.

What I want to build:
[Describe your app here]

4. このプロジェクトで今後のエージェントの動作を決める 3 つのファイル、AGENTS.md、CLAUDE.md、DESIGN.md を案内します。

この最後のメッセージは短くまとめてください。ユーザーが求めているのは、長文を読むことではなく、構築を始めることです。

公開に関する注意

他の人がこのスキルをインストールする方法をユーザーから聞かれた場合は、次のように答えます。

npx skills add <owner>/<repo>@create-agentic-app --agent claude-code

--agent claude-code フラグは必須です。これを付けないと、インストーラーはプロジェクトのルートにある 37 個以上の IDE アダプターフォルダーにスキルを配置しますが、通常は望ましくありません。