App builder(アプリビルダー)
アイデアからデプロイ、テスト、セキュリティ対策が施されたWebアプリを、あらゆるスタックで実現する再現可能な方法です。実際のプロジェクト(AI討論アリーナ:Next.js、Drizzle、Better Auth、Vercel、Turso、QStash、Vitest、Playwright)を構築する過程で犯したすべての失敗から抽出されました。コア部分(このファイル、profiles/、reference/)はスタックに依存しません。特定のプロダクトやフレームワークに固有のものはstacks/に格納され、それを使用するプロジェクトからのみ読み込まれます。手順に従ってください。プロセスをアドリブで変更しないでください。
ここから始める(毎セッション)
- プロジェクトの状態を確認する。
docs/plan.mdが存在する場合は、最初にそれを読んでください。プロファイル、決定済みの事項、現在のマイルストーンが記録されています。そこから続行し、すでに決まった質問を再度尋ねないでください。 - プロファイルを選択する(新規プロジェクトのみ)。 一度だけ、平易な言葉で尋ねてください:
「技術的な選択(コード、ホスティング、データベース)に参加しますか?それとも、それらは私に任せて、アプリの機能や見た目についてだけ質問してもよろしいですか?」
- 参加する →
profiles/technical.mdを読む - 任せる →
profiles/guided.mdを読む 回答をdocs/plan.mdの「作業の進め方」に記録します。プロファイルはどのように質問し、説明するかを決定します。以下のプロセスと品質基準は両方で同じです。
- 参加する →
- プロジェクトが使用するスタックノートを読む(下記「スタックノート」を参照)。
reference/process.mdを読み、そのフェーズに順番に従う。 フェーズが指し示すときに他のリファレンスを読み込んでください。すべてを一度に読み込まないでください。
スタックノート
stacks/には、テクノロジーごとに1ファイルが格納されています。セットアップ手順、ハマりどころ、実際のプロジェクトで学んだ修正方法です。
- 読むべきもの: 計画の「作業の進め方」セクションにそれらがリストされています(「スタックノート:nextjs, vercel, …」)。各セッションの開始時にそれらを正確に読んでください。また、プロジェクトのマニフェスト(
package.json、vercel.json、docker-compose.yml…)とユーザーのOSにも目を通し、計画に記載されていないスタックノートが存在する場合はそれを読み、リストに追加してください。新規プロジェクトでは、スタックが決定した時点(プロセスのフェーズ2)でスタックノートを選択します。 - 見逃しを防ぐために: プロジェクトの指示ファイル(すべてのセッションで読み込まれる
CLAUDE.mdまたはAGENTS.md)には、リクエストの内容にかかわらず、各セッションの開始時にdocs/plan.mdとそのスタックノートを読むように指示されています。そうしないと、このスキルをトリガーしないセッションはこのリストを見ることができません。このスキルはリポジトリの外部にあるため、優雅に動作が低下するように表現します。計画は自己完結型であり、スタックノートは「app-builderスキルがインストールされている場合」にのみ読み込まれます。 - 新しいサービスやライブラリを採用する前に、 対応するスタックノートが存在するか確認してください。
- 新しい教訓の保存場所: それが特定のプロダクトを使用している場合にのみ有効な教訓は、そのプロダクトのスタックノートに保存します(
stacks/<製品名>.md、先頭に「次の場合に読み込む:…」と記載)。汎用的な教訓は、reference/に、プロダクトを例として挙げ、そのスタックノートへのポインタとともに、汎用的な用語で保存します。例:「リモートサービスがアイドル接続を切断した場合に1回再試行する」はreference/lessons.mdに、それを実装するlibSQLフェッチラッパーはstacks/turso-libsql.mdに保存します。 - スタックノートには、学習した時点での日付付きの事実(制限、モデルリスト、価格)が記録されています。再確認してください。
既存プロジェクトの監査
既に存在するプロジェクトにこのスキルを適用するよう依頼された場合(または大きな変更後)、プロセスを再開せずに監査して報告します:
docs/plan.mdをtemplates/plan.mdと比較し、欠落しているセクションをリストアップします。reference/quality-gates.mdをセクションごとに確認します(セキュリティ、回復力、実際の測定値とLighthouseによるパフォーマンス、UIチェックリスト、両方のテーマでのアクセシビリティ、運用とクォータ)。reference/lessons.mdとプロジェクトのスタックノートにあるアンチパターンをコードで検索します。- プロジェクトが回答しなかったキックオフの質問(例:アカウントのライフサイクル、クォータの悪用)を尋ねます。
- ギャップをランク付けして報告します(実際のギャップ、計画のギャップ、優先度低、既に優れている点)、修正案とともに。所有者が拒否したギャップは、計画の「許容されるリスク」表に記録します。所有者が同意するまで何も変更しないでください。
非妥協ルール(両プロファイル共通)
- フェーズとマイルストーン:
reference/process.mdのフェーズに従って作業を進め、各マイルストーンは実行可能で、テスト済み、デモンストレーション済み、コミット済みの状態で完了し、次のマイルストーンに進みます。キックオフ時にユーザーとマイルストーンリストを合意し、docs/plan.mdで最新の状態に保ちます。 - アプリは意図したとおりに動作する: すべてのマイルストーンは実行可能な状態で終了し、実際のブラウザでデモンストレーションし、その結果をユーザーに表示します。
- 回復力: すべての外部依存関係と長時間実行プロセスに対して、「失敗したらどうするか」(ダウン、遅延、レート制限、途中でクラッシュ、配信の重複)に対する計画済みの回答が存在し、計画の障害モード表に記録され、コードで処理され、ユーザーに平易な言葉で可視化され、テストされています。
- パフォーマンス: 合意された目標(例:オーディエンスの近くで1秒以内にページが応答する)をデプロイ後に測定します。明らかに非効率な作業(インデックスなしのクエリ、不要なポーリング、過大なペイロード)は行いません。
- 品質: 各マイルストーンは
reference/quality-gates.mdのゲート(lint、型、単体テスト、E2Eテスト、ビルド、CI、UIレビューチェックリスト)を通過します。既知の重大な欠陥を未解決のままにしません。 - セキュリティ:
reference/quality-gates.mdのセキュリティチェックリストは、最終パスとしてではなく、すべてのマイルストーンで有効です。 - 保守可能な設計: ビジネスルールはプレーンでフレームワークに依存しないモジュールに単体テストとともに配置します。外部サービスは小さな継ぎ目の背後に配置します(1ファイルで交換可能)。計画とREADMEは最新の状態に保ちます。
- 適切なレベルのテスト: ルールに対する単体テスト、ユーザーフローに対するE2Eブラウザテスト、有料または低速な外部サービス(AIモデル、決済)に対するスクリプト化された偽装。
- コストを管理下に置く: ユーザーの予算は計画に明示します。コストが発生する可能性のあるものには、上限、カード不要の無料枠、またはユーザー自身のキーを設定します。
- 機密情報はチャットを経由しない: ユーザーは自分で
.env.localとホスティングのダッシュボードに機密情報を設定するか、マーケットプレイス統合が注入します(reference/third-party-setup.mdを参照)。 - まず自分で確認する: 変更またはデプロイ後は、報告したりユーザーに確認を依頼する前に、自分で結果を確認します(ブラウザ、ホスティングプラットフォームのログとCLIによるデプロイ状態、プローブスクリプト)。ユーザーに依頼するのは、サインイン、機密情報、お金、承認など、ユーザー自身が必要なものだけに限定します。自分で本番環境を確認することは、隠れたバグを発見する方法です。
- 正直な報告: 何をどのように確認したか、確認しなかったこと、失敗したことを報告します。実行しなかったチェックを主張しないでください。
- 変化する事実を確認する: 価格、無料枠の制限、ライブラリのAPIやバージョンは、それらに依存する前に現在のソース(
node_modules内のドキュメント、公式ページ)と照らし合わせて確認し、ソースを引用します。
このスキルのファイル
| ファイル | 用途 |
|---|---|
profiles/technical.md | 技術的な所有者との作業方法:何を尋ね、何を決定して通知するか |
profiles/guided.md | 非技術的な所有者との作業方法:言葉遣い、選択肢、クリックごとの指示 |
reference/process.md | キックオフから引き継ぎまでのフェーズ。各フェーズで何を生み出すべきか |
reference/quality-gates.md | 完了の定義、テスト戦略、回復力、パフォーマンス、セキュリティ、UIレビューのチェックリスト |
reference/stack-defaults.md | デフォルトのスタックとアーキテクチャ、予算の階層、逸脱すべき場合 |
reference/environment.md | ほとんどの中断を取り除く事前チェックと権限設定 |
reference/third-party-setup.md | アカウント、機密情報、ホスティング/データベース/キューの設定を最小限の手作業で行う方法 |
reference/lessons.md | すでに一度遭遇した具体的な落とし穴とその修正を、スタックに依存しない形でまとめたもの。各マイルストーンの前にざっと読むこと |
templates/plan.md | プロジェクトのdocs/plan.mdのスケルトン |
スタックノート(プロジェクトが使用する場合のみ読み込む):
| ファイル | 内容 |
|---|---|
stacks/nextjs.md | Next.js App Router、キャッシュコンポーネント、プロキシ、ルートハンドラ、サーバーアクション、React 19フォーム、開発サーバー |
stacks/vercel.md | Vercelホスティング:リージョン、環境変数と再デプロイ、CLI、ログ、ビルド時設定 |
stacks/turso-libsql.md | Drizzleを使用したSQLite/libSQL、Turso:セットアップ、マイグレーション、リモートフェッチ、アイドル接続の切断 |
stacks/better-auth.md | Better Auth:メール確認、パスワードリセット、アカウントリンク、セッションのハマりどころ |
stacks/upstash-qstash.md | Upstash QStash:ローカル開発サーバー、署名、遅延、スケジュール、クォータ |
stacks/ai-providers.md | Vercel AI SDK、Groq、Google AI Studio、OpenRouter(接続フロー、無料モデル)、Ollama |
stacks/gmail-smtp.md | ドメインなしでGmail経由でアカウントメールを送信する方法 |
stacks/playwright.md | Playwright E2Eテスト:セレクタ、非表示ページ、ローカル偽装 |
stacks/github.md | GitHubリポジトリ、Actions CI、GitHubサインイン |
stacks/google-oauth.md | Googleサインイン:Cloudプロジェクト、同意画面、ブランディング、ローカルと本番で共通のクライアント |
stacks/windows.md | Windowsでの開発:Smart App Control、PowerShell、Docker、CLI |