convex-deploy-guard

デプロイ先ガード

デプロイ先は互換性がなく、インシデントの多くは誤ったデプロイ先を対象にコマンドを実行したことから始まります。Convex プロジェクトにはそれぞれ複数のデプロイ先があります（個人用 dev、preview、prod — 1 台のマシンで複数のプロジェクトを扱うこともよくあります）。このガードは、常に守るべき手順です。対象を特定し、宣言してから実行します — また、prod はアクションごと、セッションごとに同意を必要とするものとして扱います。

ワークフロー

1. 実行前に対象を特定します。.env.local の CONVEX_DEPLOYMENT、convex.json、および CONVEX_DEPLOY_KEY が設定されているかを確認するか、公式 Convex MCP の status ツールを呼び出します。対象を local-anonymous | dev | preview | prod に分類します。情報源が食い違う場合は、先に解決してください。
2. デプロイに影響するコマンドを実行する前に、1 行で対象を宣言します。例：target: dev (joyful-capybara-123, personal dev)。対象を特定するのと同時にコマンドを実行してはいけません — まず宣言してください。
3. prod では、その都度、新たな明示的な承認が必要です。npx convex deploy（prod に解決される場合）、npx convex run --prod、prod での env set、prod でのスナップショットの import／export、または prod にアクセスできる MCP の起動を行う前に、どのデプロイ先で何が変更されるのかを正確に伝え、このセッション中に明示的な承認を得てください。以前に得た承認や、別の対象への承認は引き継がれません。
4. MCP の安全なデフォルト設定：公式 MCP は非 prod にスコープして起動します（--deployment dev）。prod 用の 2 つのフラグはリスクレベルが異なるため、分けて使います。読み取り専用の prod 監査（advisor／insights によるデータ／ログ／インサイトの読み取り）では --cautiously-allow-production-pii（読み取りツール）のみを渡します。--dangerously-enable-production-deployments（prod を変更するツールを有効にする）は、ユーザーがこのセッション中に prod を変更するよう明示的に依頼しない限り、無効のままにします。デフォルトで両方を組み合わせてはいけません — 「prod を見て」が、ひそかに「prod を変更して」まで許可することがあってはなりません。
5. 読み取り専用セッションモード：ユーザーが「読み取り専用」／「何も変更しないで」と言った場合は、セッションの残りの間、絶対にその指示を守ります — デプロイ、env の設定／削除、run による変更、インポートは行わず、MCP は --disable-tools run,envSet,envRemove を付けて起動します。
6. 誤ったデプロイ先の診断：「デプロイしても何も変わらなかった」場合、さらに強引に再デプロイしてはいけません。ステップ 1 をやり直してください — ほぼ確実に、確認しているデプロイ先とは別の場所にデプロイされています。
7. 曖昧な場合は停止します。コマンドがどのデプロイ先を対象にするのか判断できない場合は、確認してください（status ツールを使う、または npx convex env list のフィンガープリントを比較する）— 絶対に推測してはいけません。

ルール

• デプロイに影響するコマンドを実行するたびに、対象を分類して宣言してください — 特定と実行は別々の手順です。
• prod への同意は、アクションごと、対象ごと、セッションごとに必要です。どこで何が変更されるのかを伝え、その都度、新たに明示的な承認を得てください。
• prod 用の 2 つの MCP フラグはリスクに応じて分けて使います。監査には読み取り専用の --cautiously-allow-production-pii を使用し、prod を変更するようユーザーが明示的に依頼した場合に限り、変更用の --dangerously-enable-production-deployments を使用します。どちらもユーザーが明示的に指示した場合にのみ使用し、MCP は毎回、デフォルトで非 prod のデプロイ先セレクターを指定して起動します。
• 読み取り専用モードは、一度要求されたらセッション中は絶対です — 「無害な」変更も禁止です。
• デプロイしても何も起きなかったように見える場合、変更されたのは誤ったデプロイ先です — 対象を診断し、再実行してはいけません。
• このガードは他の手順と組み合わせて使います。ship、env、migrate、seed はステップ 0 としてこのガードを実行します。このガード自体はデプロイツールではありません。