deploy-an-app

アプリをデプロイする

1台のマシンで動作するアプリを、誰もが使えるようにします。完成するのは、実際のインフラストラクチャを基盤とし、ユーザーが所有するライブ URL です。ユーザーに代わって行ったことと、ユーザー自身が引き続き対応することも正直に伝えます。

デプロイは開発ではありません。 このスキルでは、インフラストラクチャを用意し、設定を行い、デプロイを実行します。機能の追加、ページの再設計、気に入らないコードの改善は行いません。本番環境で実行するためにコードの変更が本当に必要な場合――該当する一般的なケースは、SQLite アプリを Postgres に移行する場合の1つだけです――その変更はステップ3のシートに記載し、実行前に承認を得ます。

この作業の大半は自動化でき、自動化できない部分も事前に把握できます。 このスキルの価値は、vercel deploy と入力することではありません。人間にしか用意できない認証情報をすべて、作業を始める前に1か所で一度だけ求めることです。ビルドが失敗するたびに1つずつ見つけるのではなく、まとめて確認します。

基本ルール

• コードを書かないけれど理解力のある友人に説明するように、すべての手順を説明してください。「ドメイン」と言う前に「人が入力するアドレス」と説明してください。用語はそれぞれ最初に一度だけ簡潔に説明し、その後は通常どおり使ってください。
• バージョン番号は絶対に書いたり、受け入れたりしないでください。 インストールコマンドでも、説明文でも、条件判定に使う CLI のバージョンでも同じです。すべての実行では現行リリースを使い、現時点でそれが何を意味するかを確定するのがステップ 1 です。スキルファイルに書かれたバージョンは、タイムスタンプ付きの嘘です。
• 非推奨のものは一切使わないでください。 現行リリースで参照ファイルに記載されたものの名前が変更されたり、後継に置き換えられたりしている場合は、「まだ動く」古い方法ではなく、置き換え後のものを使ってください。
• ホスティング CLI でできることについては、何よりも --help を優先します — このファイル、参照ファイル、ステップ 1 の調査、プロバイダー自身のドキュメントよりも優先します。ドキュメントが説明しているのは、執筆者が使っていたリリースです。これから実行するバイナリに確認してください。これは、API の詳細では調査結果を優先するという親スキルのルールに対応する、デプロイ側のルールです。
• 公開 URL はプラットフォームから取得し、決して予測しません。 名前が重複するとホストが別の名前を割り当てるため、推測した URL に基づく値はすべて、サインイン用オリジン、OAuth コールバック、トークンのオーディエンスに至るまで、気付かないうちに誤ったものになります。
• ビルドに必要なものはすべて、ビルドの開始前に設定します。 データベースだけではありません。プロバイダークライアントはモジュールが初めてインポートされたときに構築されるため、キーがなければビルドに失敗し、実行時の警告にはなりません。ステップ 7 が終わってからステップ 8 を開始してください。
• .env はデプロイ成果物ではありません。 含まれる値の中には、本番環境では積極的に危険なものもあります。たとえば、ローカルデータベースのアドレス、決済のサンドボックス用フラグ、署名チェックを無効にするスイッチなどです。それぞれを意図的にコピー、変換、再生成、または拒否してください。対応表は references/env.md にあります。まとめてコピーする処理はありません。
• シークレットは、取得元からホストへ渡すだけにしてください。それ以外の場所には渡さないでください。 表示したり、会話に書き出したり、ファイルや環境変数で渡せるものをチャットメッセージで尋ねたりしてはいけません。
• 承認は一度だけで、予告する中断も一度だけです。 ユーザーが何かを決定するのはステップ 3 だけです。ステップ 6 は予定された引き継ぎで、API ではできないブラウザー操作をユーザーが行います。実施前にチェックシートに記載しておくので、突然の中断ではなく予定された打ち合わせになります。
• ユーザーが別途指定しない限り、テストモードを使ってください。 チェックシートにあるそれ以外の作業は、まとめて一度の承認で実行します。ただし、実際の決済は別です。実際のカードに請求できる唯一の操作であり、本番価格は後から削除できないためです。
• 作成前に確認し、作成したものを記録してください。 ここで扱う各プロバイダーは、同じものをもう一つ作成しても問題なく動作します。同じ URL に Webhook が 2 つあると、すべてのイベントが 2 回処理され、その半分で署名チェックに失敗します。記録は作成のたびに書き、後から再構成してはいけません。形式は references/recovery.md にあり、中断した実行の状況を報告可能にし、不明な状態にしないために使います。
• 問題が起きたら停止して報告し、決して取り消し処理をしないでください。 後続のステップから接続できなかったデータベースにも、正常に動作したスキーマは残っています。取り消せるものと取り消せないものは references/recovery.md に記載されています。
• この実行で作成していないものは、削除も上書きもしないでください。 名前が重複した場合は停止してユーザーに確認します。この実行で自ら書き込んだ値を修正する場合は例外です。
• 実行していないチェックは、実行したかのように主張せず、未実行だと明記してください。 このスキルで特に誤認を招きやすいのは、名前を読み取っただけなのに環境を検証済みと言うこと、ページが 200 を返しただけなのにデータベースに接続済みと言うこと、エンドポイントを登録しただけなのに Webhook が機能すると言うことです。ユーザーは、何も言われなければ成功したと受け取ります。
• ゲートは、デプロイを修正して通過してください。ゲートを緩めてはいけません。 ビルドエラーを無視したり、検証を省略したりしてはいけません。特に、赤い X を緑にするためにビルドスクリプトからマイグレーション手順を削除してはいけません。
• 絶対に drizzle-kit push を実行しないでください。 これは親スキルのルールであり、ここで扱うデータベースにはユーザーの実データが入っています。
• アプリは現在の作業ディレクトリからデプロイします。このフォルダーがプロジェクトルートです。サブフォルダーを作成したり、そのフォルダーに cd したりしてはいけません。
• すべてのコマンド、パッケージ名、設定は、このファイルではなく参照ファイルに記載します。検出された分岐で必要なものだけを読み込んでください。
• ツールの変更が原因で参照コマンドに失敗した場合は、そのツールの公式ドキュメントを確認し、現行の代替手段を使って作業を完了してください。最後に、更新が必要なファイルをユーザーに伝えてください。

ステップ 0 — 事前確認

何かを約束する前に、事実を確認します。references/preflight.md。

ここでは何も変更しません。ホスティング CLI が利用可能か、実際に何ができるか、ユーザーがログインしているか、どのアカウントでログインしているか、このアプリが何か、どのパッケージマネージャーを使っているか、ビルドコマンドが実際に何を実行するか、コードを確認して判明する機能、コードが読み取る環境変数の完全な一覧、そして Git ツリーがクリーンかどうかを確認します。

ブランチの一覧はコードから取得します。 アプリに決済機能があるのは、ユーザーが言及したからではなく、決済クライアントが組み込まれているからです。これにより、このスキルを自分で構築していないアプリでも使えます。

作業ツリーが汚れている場合は、ここで停止します。 コミットされていない作業からのデプロイは、誰も再現できないビルドです。また、2 つのデプロイ方法（プッシュと直接アップロード）では、デプロイに含まれるものが一致しません。

ユーザーがいる本番デプロイは、すでに存在していますか？ 存在する場合は、この実行の残り全体で方針を変更します。何もゼロから作成せず、ステップ 8 では本番環境へ直接デプロイしません。必要になる段階ではなく、ここで確認します。

ステップ 1 — 最新情報を確認する

ブランチが判明したので、今日それらをデプロイするには何が必要かを調べます。親スキルと同じパターンです。検出したブランチごとに 1 つの調査サブエージェントを割り当て、すべてを 1 回のメッセージで同時に実行します。

ホスティング CLI、ダッシュボード、プロバイダー API はアプリケーションライブラリよりも速く変更され、その変更は型ではなくスクリプトを壊す形で発生します。フラグ名が変更されただけでパイプラインが途中で停止し、すでにリソースが作成されてしまうこともあります。

各サブエージェントには標準の指示を出します。現在の安定版リリース、非推奨になったものや名称が変更されたもの、現在のコマンドとエンドポイントの形式、そして参照ファイルの手作業を置き換える新機能が追加されているかを調べます。親スキルと同じ方法で調査結果をまとめます。最新の安定版のみを採用し、新機能があればそれを使います。各要素の組み合わせ方については、このスキルの内容を優先します。

ユーザーに伝えるのは、変更があった場合だけです。 調査してすべて問題ないと分かったことを逐一説明すると、余計な情報に感じられます。

ステップ 2 — ユーザーしか知らないこと

ステップ 0 で大半はコードから判明しているため、短く済ませます。推薦事項を添えて、質問は一度に 1 つずつします。

1. 「どのアドレスで公開しますか？」 — 所有しているドメイン、またはホスティングサービスが提供する無料のドメインです。コールバック URL、Webhook の送信先、サインインのオリジンはすべてここから決まるため、最初に尋ねます。後から変更するたびに、手作業が二度発生します。
2. 検出したブランチに必要な認証情報は、1 つのブロックにまとめて確認します。各プロバイダーのアカウントとキー、それぞれの用途、入手先を確認します。問題が起こるたびに個別の質問をすることはありません。
3. 決済機能がある場合は、テストモードにするか、実際に課金するか。 テストモードを推奨します。実際に課金する場合は、別途明示的な確認が必要です。

ステップ 3 — デプロイ内容の確認

平易な言葉で説明し、明確な承認を一度もらいます。start-an-app のステップ 3 で、デプロイに関して行うことは次のとおりです。

TrailLog 用に、次のものを設定します。

公開先： traillog.com — ドメイン登録業者で DNS レコードを 2 つ追加していただきます。必要な内容は正確にお伝えします。 データベース： ホスト型の Postgres（無料枠）です。利用がない間は休止するため、しばらくアクセスがなかった後の最初の訪問では、表示まで 1 秒ほどかかります。 写真： プロジェクトに接続するファイルストアです。一定の範囲までは無料です。 サインイン： Google のコンソールにコールバック URL を 1 つ貼り付けていただきます。2 分ほどで終わり、正確な入力内容をこちらでお伝えします。 決済： テストモードで設定します。許可をいただくまで、実際のカードは使いません。 費用： 今日の時点では無料です。すべて無料枠で利用でき、それぞれの無料枠がどこで終わるかもお伝えします。 一時停止する箇所： アドレスの設定後、いったん止まり、ブラウザーで行っていただく作業を簡潔にまとめてお渡しします。DNS レコードと Google のコールバックです。それ以外の作業で中断することはありません。

よろしいですか？

作成するもの、費用、取り消せない操作、一時停止する箇所を含めます。SQLite アプリの場合は、コードを変更することをここで平易な言葉で説明します。

ステップ 4 — アドレス

後続のすべての作業で URL が必要になるため、ほかのものを作成する前に確定します。references/project-and-url.md。

プロジェクトを作成し、プラットフォームが実際に割り当てた本番 URL を読み返して確認します。カスタムドメインがあれば接続し、ユーザーが必要とする DNS レコードを提示します。DNS の設定は早めに始めます。パイプラインの中で最も時間がかかり、ほかの作業には依存しないためです。

ドメインを使う場合は、正規ホストをルートドメインか www のどちらかに決め、もう一方からリダイレクトします。誤ったホストに設定されたセッション Cookie は、サインインできたように見えて、その後うまくいかない原因になります。

ステップ 5 — プロビジョニングと準備

references/provision-database.md。アップロードを使う場合は、references/provision-storage.md も参照します。

データベースとファイルストアを作成し、プロジェクトに接続します。成否を左右する点が 2 つあります。プロバイダーが設定する名前と、コードが読み取る名前が異なる場合があること、そしてマイグレーションには直接接続文字列が必要ですが、アプリにはプール接続文字列が必要なことです。

必要に応じて、ここでコードも変更します。SQLite からの変換と、変数名の整合です。変更をコミットします。

その後、デプロイ前に、本番データベースを使ってローカルでビルドします。 プラットフォームで実行されるのと同じ、マイグレーション後にビルドする手順を実行します。変換の問題やモジュールスコープで参照されるキーをすべて検出でき、デプロイを消費しません。このスキルで最も費用対効果の高い確認です。

ステップ 6 — 引き継ぎ

事前に伝えておく、唯一の一時停止です。ブラウザーで人の作業が必要なものをすべて、1 つのまとまりにしてユーザーに渡します。DNS レコード、OAuth コールバック URL、まだ必要なプロバイダーアカウントなどです。値は正確に記載し、そのまま貼り付けられるようにします。

これは判断を求めるためのプロンプトではありません。判断はステップ 3 です。あらかじめ約束した予定どおりの引き継ぎなので、ユーザーは 5 回中断されることなく、15 分ほどのコンソール作業を一度に済ませられます。

ステップ 7 — 環境変数

references/env.md。ビルドを行う前に、コードが読み取る変数をすべて本番環境に設定します。

単にコピーするだけでは済まない理由は 3 つあります。コピーせず変換または拒否する必要がある値、目に見えない末尾の改行で壊れても診断のために読み返せないシークレット、そして書き込んだシークレットは「存在する」ことは確認できても「正しい」ことは確認できないという点です。

次に、稼働中のサイトではなく URL だけを必要とする外部システムを接続します。決済 Webhook、バックグラウンドジョブのキーなどです。該当するブランチがある場合に限り、それぞれ references/wire-payments.md、references/wire-jobs.md、references/wire-auth.md、references/wire-email.md、references/wire-mcp.md を参照します。

ステップ 8 — デプロイ

references/deploy.md。一度だけです。 ビルドに必要なものはすでにすべて揃っているため、最初のデプロイは、データベースがないために失敗する使い捨てのものではなく、成功する最初のデプロイになります。

ユーザーがリポジトリを持っている場合は接続し、プッシュによってデプロイできるようにします。そうすれば、今後ずっと使う仕組みを、実際に動作することまで確認できます。直接アップロードは代替手段です。

次に、公開されたデプロイが、想定しているコミットであることを確認します。コマンドは一つで、新しいビルドが進行中なのに前回のビルド結果を読み取ってしまうことと、コミットされていないものをデプロイしてしまうことという、最もよくある二つの誤った成功を見抜けます。

この実行で作成したプロジェクトに限り、本番環境へ直接デプロイします。 すでにユーザーがいる公開サイトがある場合は、対応方針が異なります。その場合は references/deploy.md を参照してください。

ステップ 9 — 検証

references/gate.md。アプリはデプロイされました。しかし、動作することを裏付けるものはまだありません。

公開 URL に対してコマンドを実行し、その出力を読み取ります。ブラウザーなしで外部から実際に検証できることは、思った以上にあります。デプロイされたコミット、マイグレーションが実行されたこと、データベースが応答すること、すべてのルート、証明書と正規ホスト、Cookie のフラグ、Webhook エンドポイントが何でも受け入れるのではなく署名を検証すること、そして検出用ドキュメントに実際のドメインが記載されていることです。

失敗とブロック中と未試行を区別します。 DNS がまだ反映されていない場合、ドメインに依存するチェックはすべて一つの原因で失敗します。一つの原因に対して15件の失敗を報告しても、ユーザーがゲートを無視するようになるだけです。

ブラウザーを使える場合は利用します。公開ドメインで実際にサインインすることは、URL、データベース、セッション Cookie がすべて正しいことをまとめて証明する唯一のチェックです。それでも確認できない項目は、未実施として明記します。

ステップ 10 — 新たな視点

ゲートによって、サイトが応答することは確認できます。しかし、デプロイが合意どおりに行われたか、あるいは何かを残していないかは判断できません。批評担当を一度のメッセージで割り当てます。 読み取り専用で、アクセスではなく証拠を確認し、2ラウンドで終了します。依頼内容は references/gate.md にあります。

新しいアプリをレビューするのではないため、確認する視点は親スキルのものとは異なります。仕様と実態、主張と証拠、秘密情報の露出、そして残されたものです。

ステップ 11 — 引き継ぎ

• 現在あるものとその費用。作成中に記録した情報から、すべてのリソース、各無料枠の上限、削除方法を伝えます。
• 次の git push で何が起きるか。 プッシュによるデプロイが設定されている場合、これは作業方法における最大の変更であり、平易な一文で伝える必要があります。メインブランチへのプッシュで本番環境に反映され、マイグレーションに問題があればビルドは失敗します。
• 再デプロイの方法とロールバックの方法。
• 実行できなかったすべてのチェックと、それぞれの実行に必要なもの。
• まだ残っている手動の手順（合流時に残ったものがある場合）。
• エージェントアクセスを構築した場合は、コネクター URL と Claude での設定場所。ユーザーが自力で見つけることはできません。
• ステップ 1 の調査結果と矛盾していた事項。スキルを修正できるよう、明記します。