本番対応のハンドオフチェックリスト（セルフホスティング向け）

「本番対応のハンドオフ」が実務で意味すること\n\n本番対応のハンドオフとは、運用が推測せずにアプリを運用できる状態を指します。既知のバージョンをデプロイでき、正常性を確認し、アラートに対応し、リリースや障害から復旧できること。これらのいずれかが特定の開発者の記憶に依存しているなら、ハンドオフは完了していません。\n\nハンドオフは「もし開発者が1週間姿を消しても、運用がシステムを安全に利用可能に保てるか？」という問いに答えるパッケージと考えましょう。\n\n良いパッケージは通常、アプリの機能、正常性の定義、リリース手順（デプロイ、検証、ロールバック）、設定の場所、シークレットの扱い、監視・バックアップ・インシデント対応の方法をカバーします。\n\n同じくらい重要なのはカバーしない事項です。ハンドオフは機能追加やリファクタ、画面設計のやり直し、後で「きれいにする」ことを約束するものではありません。それらは別のプロジェクトとしてスコープを定義してください。\n\n完了と呼ぶ前に、所有権と応答時間に合意しておきます。例：運用は稼働率とデプロイを担当、プロダクトはロードマップの変更を担当、開発チームはハンドオフ後の短期間のサポート（不具合対応や質問）を提供する、など。\n\n## 簡潔なシステム目録を作る（どこで何が動いているか）\n\n運用は見えるものだけを管理できます。1ページ程度の目録はデプロイやインシデント、監査時の推測を防ぎます。平易な日本語で具体的に書きましょう。\n\nバックエンド API、ウェブアプリ、バックグラウンドワーカー、定期ジョブ、モバイルアプリがどのように接続するかなど、システムの各実行要素と配置場所を一覧にします。iOS/Android がストア経由で配布されていても、バックエンドに依存する点は同様です。\n\nアプリが依存する外部サービスも必ず含めます。PostgreSQL、キュー、オブジェクトストレージ、第三者 API（Stripe のような決済、メッセージング、メール/SMS、Telegram など）を使っているなら、正確なサービス名と用途を書きます。\n\nホスティングで試行錯誤にならないよう、ネットワーク要件も記録します：必要なドメイン（app、api、admin）、ポートとプロトコル、TLS証明書の更新担当、DNSの管理先、着信/発信の許可リストなど。\n\n最後に期待される負荷を実数で書きます：ピークの分あたりリクエスト数、アクティブユーザー数、典型的なペイロードサイズ、現在のデータベースサイズと予想成長率。大まかな範囲でも運用がしきい値やアラートを設定する助けになります。\n\nAppMaster で構築している場合は、生成されたバックエンド、ウェブアプリ、統合の一覧も含めて、運用がどれを一緒にデプロイする必要があるかがわかるようにしてください。\n\n## 環境設定をパッケージ化する（シークレットは公開しない）\n\n多くの本番環境で失敗するのは地味な部分、すなわち「設定が誰かの頭の中だけにある」ことです。設定を成果物として扱ってください。運用がどの設定が存在し、環境ごとに何が違い、どう安全に変更するかを見られるようにします。\n\nまず、今日存在するすべての環境名を列挙します。仮であっても書き残してください。多くのチームは dev、staging、本番の他に「production-eu」や「staging-us」などのコピー環境を持っています。どの環境がリリーステスト、データマイグレーション、障害訓練に使われるかも示します。\n\n設定キー名と安全な例値（本物の資格情報ではない）を一覧にした単一の設定リファレンスを用意します。プレースホルダーは明確にしてください。\n\nハンドオフパッケージに含めるものの例：\n\n- 環境一覧とそれぞれの用途\n- 設定キーのリファレンス（環境変数や設定ファイルのキー）、期待される型、秘密でない例値\n- 環境間の既知の差分（フィーチャーフラグ、レート制限、キャッシュサイズ、メールモード、ログレベル）\n- デフォルト値とキーがない場合の挙動\n- 設定がどこに保存され、デプロイ時にどう適用されるか\n\n簡単な変更プロセスも追加してください。例：チケットで要求、サービスオーナーがレビュー、まずステージングで適用、運用ウィンドウで本番に昇格、エラーレート上昇時のロールバック計画を用意する、など。\n\nAppMaster をエクスポートしてセルフホストする場合でも同じルールを守ってください：生成されたソースに沿って、クリーンで文書化された設定キーのセットを同梱し、運用が各環境で一貫して実行できるようにします。\n\n## シークレットと資格情報：保管、ローテーション、アクセス\n\nシークレットは、きちんとしたハンドオフがセキュリティインシデントに変わる最短ルートです。目標は明確です：運用側がアプリに必要な全シークレットを把握し、どこに保存され、誰が読めて、ダウンタイムなしで変更できるかを理解すること。\n\nまずは運用が1分で確認できる短いシークレット一覧を作ります。各項目について、そのシークレットが何を解錠するか（データベース、SMTP、Stripe、JWT 署名キー）、どこにあるか（Vault、クラウドシークレットストア、Kubernetes Secret、暗号化ファイル）、そして誰が回転を担当するかを書きます。\n\n回転手順はポリシーではなくレシピのように書いてください。正確な順序、古いシークレットをどのくらいの期間残すか、動作確認のための1つのチェックを含めます。\n\n### 回転チェックリスト（例）\n\n各シークレットに次のパターンを適用します：\n\n- 新しいシークレット値を作成して承認されたシークレットマネージャに保存する。\n- アプリが新しい値を使うように設定をデプロイする。\n- 検証：ログイン、決済、API 呼び出しが成功し、エラー率が通常の範囲にあることを確認する。\n- 古いシークレットを取り消し、もう動作しないことを確認する。\n- 回転日時、実施者、次回の期限を記録する。\n\n暗号化要件は明示してください。シークレットは保管時に暗号化され、アプリと依存先間の通信は TLS で保護されるべきです。シークレットをソース管理、ビルド成果物、共有ドキュメントに置いてはいけません。\n\n緊急時のブレイクグラスアクセスを定義します。障害で通常のアクセスができない場合に誰が承認し、どのくらいの期間有効にできるか、事後にどのように監査するかを明記してください。\n\n## デプロイパッケージ：成果物、バージョン、ロールバック\n\n運用は再現できるものだけを管理できます。良いデプロイパッケージは次の3つの質問に答えられるようにします：今何を動かしているか、同じものをどうデプロイするか、問題が起きたらどう速やかに戻すか。\n\nビルドの明確な「部品表」を含めます。場所だけでなく検証方法も書くこと：\n\n- アーティファクトの詳細：コンテナイメージ名/タグ（またはバイナリ/パッケージ名）、アプリのバージョン、ビルド日、チェックサム\n- ソース参照：ビルドに使ったリリースタグやコミットハッシュ、関係するビルドフラグ\n- サポート対象：VM、コンテナ（Docker）、Kubernetes のいずれか、推奨デフォルトを明記\n- デプロイ手順：前提条件（ランタイム、DB、ストレージ）、正確な順序、典型的なデプロイ所要時間\n- データベースマイグレーション：自動実行か手動か、ログの場所、成功確認方法\n\n小さな具体例を一つ入れてください。例：「v1.8.2 をデプロイするにはイメージタグを更新し、マイグレーションを実行してからウェブワーカーを再起動。10分以内にヘルスチェックが通らなければ v1.8.1 に戻し、マイグレーションジョブを停止する。」\n\n### 推測の余地を残さないロールバック\n\nロールバック計画は、午前2時でも従える命令書であるべきです。次を明示してください：\n\n- ロールバックを引くシグナル（エラー率、ヘルスチェック失敗、ログイン障害など）\n- 最後に確実に動いていたバージョンとその保管場所\n- データベース変更が可逆かどうか、不可逆の場合の対処法\n\nAppMaster で構築してソースをエクスポートしている場合は、生成コードのバージョン、ビルド手順、ランタイム要件を含めて、運用が同じリリースを後で再構築できるようにしてください。\n\n## 監視とアラート：何を測り、いつページすべきか\n\nハンドオフは、運用がアプリの状態を見られ、ユーザーが不満を言う前に通知を受け取れるようにすることが完了条件です。\n\n必要なログの種類と保存先（ファイル、syslog、ログプラットフォーム）を合意し、ログが時刻同期され、リクエストや相関 ID を含むようにしてインシデントを追跡できるようにします。\n\n通常必要なログ：アプリログ（重要イベント、失敗）、エラーログ（スタックトレース、失敗したジョブ）、アクセスログ（リクエストとステータスコード）、監査ログ（管理操作、エクスポート）、インフラログ（再起動、ノード負荷、ディスク問題）など。\n\n次に、ユーザー影響とシステム健全性を反映する小さな指標セットを決めます。5つに絞るなら：レイテンシ（p95/p99）、エラー率、飽和（CPU/メモリ/ディスク）、キュー深度、外部からの可用性チェックです。\n\nアラートルールは明確にします：発火条件、重要度（ページかチケットか）、オンコール担当、エスカレーション方法。正常なダッシュボードのスナップショットと、通常の見え方（典型的なレイテンシ範囲、許容エラー率、通常のキュー深度）を短く添えると、不要なノイズを減らし新しい担当者の判断を助けます。\n\n## バックアップと復元：復元手順を反復可能にする\n\nバックアップは「ある」ではなく、オンデマンドで「復元できる」ことが重要です。\n\nバックアップの対象範囲を正確に書きます：データベース、ファイルストレージ（アップロード、レポート、請求書など）、設定でコード外にあるもの、保護データを読むための暗号化キーなどを含めます。\n\nRPO（どれだけデータを失えるか）と RTO（どれくらいで復旧するか）をビジネスと合意した数値で決めてください。これらがコストと工数を左右します。\n\n含める項目の例：\n\n- 何をバックアップするか、保存場所、保持期間\n- 誰がバックアップ／復元を実行できるか、アクセス承認の方法\n- ステップバイステップの復元手順と検証チェック\n- 復元ログの保存場所と「成功」の定義\n- よくある失敗モード（誤った鍵、バケット欠落、スキーマ不一致）とその修正方法\n\nAppMaster からエクスポートしてセルフホストする場合は、PostgreSQL の復元手順や外部ストレージバケット、暗号化フィールドに使うキーも含めてください。\n\n復元ドリルをスケジュールし、実行時間・障害内容・変更点を記録しておくと、次回はより速くストレス少なく復元できます。\n\n## ランブックとオンコール：実際のインシデントを運用する方法\n\nハンドオフは、実際に誰かが午前2時にページを受けて推測なしで問題を解決できて初めて意味を持ちます。ランブックは部族的知識を誰でも使える手順に変えるものです。\n\nまず想定される代表的なインシデントを優先します：完全な停止、レスポンスの遅延、デプロイによる障害。各ランブックは短く保ち、最初に行うべき高速なチェックを上部に置いてください。\n\n### 良いランブックに含めるもの\n\n一貫した構成にして、プレッシャー下でも読みやすくします：\n\n- ユーザーが見る症状とそれを確認する方法（例：エラー率が X% を超えている、チェックアウトが失敗する）\n- 最初にするチェック（サービス状況、最近のデプロイ、依存先の健全性、ディスク/CPU、DB 接続）\n- 次に見るもの（開くべきログ、重要なダッシュボード、最近の設定変更、キュー深度）\n- 判断ポイント（いつロールバックするか、いつスケールするか、いつ機能を無効にするか）\n- エスカレーション先（アプリ担当、インフラ担当、いつ誰にページするか）\n\nAppMaster からエクスポート／セルフホストしている場合は、生成されたサービスがどこで動くか、どのように安全に再起動するか、環境ごとに想定される設定値を含めてください。\n\n### インシデント後：正しい事実を記録する\n\n短い事後チェックリストを持ちます。タイムライン、直近に行われた変更、正確なエラーメッセージ、影響を受けたユーザー、問題を解決したアクションを記録し、詳細が新鮮なうちにランブックを更新します。\n\n## アクセス制御と権限：誰が何をできるか\n\n誰が何を操作できるかが明確で、アクセスが追跡できることは運用がシステムを所有するための前提です。\n\n実際に使っている役割を記載します。多くのチームで十分な役割の例：\n\n- デプロイヤー：承認済みバージョンをデプロイし、ロールバックを実行\n- DB 管理者：スキーマ変更とバックアップ復元を実行\n- 閲覧専用：ダッシュボード、ログ、設定を編集せずに参照\n- インシデントコマンダー：障害時に緊急アクションを承認\n\n「ドアポリシー」を平易な手順で文書化します：誰がアクセスを付与するか、どこで付与するか（SSO、クラウド IAM、DB ユーザー、CI/CD、管理パネル）、誰が剥奪できるか、オフボーディング時に削除されたことをどう確認するか。\n\n非人間によるアクセスも忘れずに。ジョブ、統合、監視で使われるサービスアカウントやトークンをすべて列挙し、各々に対して最小権限を記します（例：「バケット X からのみ読み取り可能」）。AppMaster からソースをエクスポートしてセルフホストする場合は、これらの識別情報がどの環境変数や設定ファイルで定義されるかを含めますが、秘密値をハンドオフ文書に貼り付けてはいけません。\n\n監査ログ要件も設定します：何をログに残すか（ログイン、デプロイ、設定変更、DB 管理操作）、誰がログを読めるか、保持期間、ログの保存場所、インシデントやレビュー時にログを要求する方法など。\n\n## セキュリティとコンプライアンスの基本（平易な言葉で）\n\nセキュリティ注記は非専門家でも読めるようにしつつ、運用が行動に移せる具体性を持たせます。1ページの要約で「どのデータを保存しているか、どこにあるか、誰がアクセスできるか」を答えられるようにします。\n\nまずデータ種別を書きます：顧客プロファイル、サポートチケット、決済メタデータ、ファイルなど。PII（氏名、メール、電話番号）や資格情報、社内で規制対象となるデータがあれば明記します。AppMaster からセルフホスト用にエクスポートした場合は、どのデータが DB のどこに入るか、どのサービスがそれを読めるかを記してください。\n\n次に保持と削除ルールを実務的に書きます。何をどれだけの期間保持するか、削除がどう機能するか（ソフトデリートかハード削除か、遅延パージか）、法的保留や監査の例外がある場合は誰が承認するかを示します。\n\nログはデータベース以上に情報漏洩しやすいので注意を払います。PII がどのログに現れる可能性があるか（アクセスログ、エラーログ、分析イベント）を明記し、マスク方法やログ出力禁止フィールドを定めてください。\n\n承認を明確にします：\n\n- 認証設計の変更は名前付き承認者が必要\n- 決済関連の変更（Stripe キー、Webhook エンドポイント、返金ロジック）は名前付き承認者が必要\n- ロールと権限モデルの変更は名前付き承認者が必要\n- セキュリティパッチの適用ウィンドウと緊急変更ルールを文書化\n\nもし一つだけ追加できるなら、証跡ノートを追加してください：監査ログがどこにあり、誰かが証拠を求めたときにどうエクスポートするか。\n\n## ハンドオフの例：運用が1週間で引き継ぐシナリオ\n\n小さなプロダクトチームが作ったカスタマーポータルを運用が新しいセルフホスト環境に移すケースを想定します。目標は「動くこと」だけでなく「運用が開発者に電話せずに運用できること」です。\n\n### 週の流れ例\n\nDay 1: 運用がハンドオフパッケージだけで新環境にクリーンな初回デプロイを行います。アプリは起動するが、メールプロバイダ用の環境変数が抜けていてログインに失敗します。env テンプレートに追記してから、初期状態から動くまで繰り返しデプロイします。\n\nDay 2: 意図的に最初のアラートを発生させます。1つのサービスを停止するか送信メールをブロックし、メトリクスとアラートが正しいチャンネルに届き、メッセージが次の手順を示すことを確認します。\n\nDay 3: サンドボックスのトークンが期限切れになります。資格情報の場所と回転手順が文書化されているため、運用は推測せずに交換できます。\n\nDay 4: DNS 切り替え。誤ったレコードが古い IP を指しており、一部ユーザーでポータルが見えません。運用はランブックに従い、DNS、TLS、ヘルスチェックの順で確認します。\n\nDay 5: 最初のバックアップ復元テスト。運用は新しいデータベースに復元し、実際のデータでポータルが読み込めることを証明します。\n\n### 1週間での「完了」像\n\n7日間謎の修正なしに稼働し、1件の成功した復元、明確なアラート、一貫して運用が単独で実行できるデプロイが確認できれば完了です。\n\n## セルフホスティング引き継ぎでよくあるミス（夜中のインシデントに繋がる）\n\n「運用に全部伝えた」は「運用が自分たちで回せる」と同義ではありません。これを誤ると深夜の火事になります。\n\nセルフホスティングのハンドオフ後に起きやすい失敗パターン：シークレットがスプレッドシートやチャットで共有されている、ロールバックが開発者依存、バックアップは存在するが復元未検証、アラートが鳴りっぱなし（閾値未調整）、設定の詳細が誰かの頭にしかない（ポート、DNS 名、cron、クラウド権限）など。\n\n例：AppMaster からソースをエクスポートしてセルフホストし、初回デプロイはうまくいった。2週間後に設定変更でログインが壊れる。シークレットがチャットで渡され、ロールバックに元の開発者が必要だとすると、運用は「昨日動いていた状態」に戻すのに何時間も費やします。\n\n## 「ハンドオフ完了」と言う前の簡単チェック\n\nチケットを閉じる前に短いフレッシュスタートドリルを行ってください。運用エンジニア1人とクリーンな環境（新しい VM、新しい Kubernetes ネームスペース、空のクラウドプロジェクト）を与え、パッケージだけでデプロイ・観察・復旧できるかを試します。時間制限（例：2時間）内に完了すれば合格に近いです。\n\nチェック項目：\n\n- パッケージ済みのアーティファクト、設定ドキュメント、ランブックだけで最初から再ビルドとデプロイ（ロールバック含む）\n- すべてのシークレットが合意された場所にあり、回転手順が書かれテストされているか\n- ダッシュボードが基本的な問い（稼働しているか、遅いか、エラーか、リソース不足か）に答えられるか\n- 安全なテストアラートを1件発生させて、ページング、担当者、サイレント時間が期待通りか確認する\n- 別環境に対する実際の復元テストを実行し、正確な手順と期待結果を文書化する\n\n生成されたソースコードをセルフホスト用にエクスポートする場合は、運用がビルド入力、バージョン、リリースタグの記録場所を把握しているかも確認して、将来のリリースが再現可能であることを担保してください。\n\n## 次のステップ：所有権を確定し、パッケージを最新に保つ\n\n最終的にページを持つ人たちと一度ウォークスルーを行ってください。デプロイ、ロールバック、復元、アラートを実際に同じパッケージで動かし、運用が一人で回せることを証明します。\n\n最終ウォークスルーでは通常、テスト環境と本番で同じ手順でデプロイ、以前のバージョンへのロールバック検証、クリーンな環境へのバックアップ復元と簡単な操作確認（ログイン、レコード作成、メッセージ送信）、安全なテストアラートの発火、インシデント時にログとダッシュボードの所在を確認します。\n\n所有権を明確にします。各ランブック（デプロイ、インシデント、復元）と各アラートルートに対して名前付きのオーナー（プライマリ、バックアップ、時間外の挙動）を割り当てます。誰もアラートを所有しなければ、それは放置されるか間違った人を起こすことになります。\n\nDay 2 の短い計画を書いて、運用が最初の週の後に何を改善すべきか（閾値の調整、コストチェック、古いアーティファクトの掃除、アクセスレビュー）を示してください。小さく時間枠を区切って実行可能にします。\n\nAppMaster（appmaster.io）で構築している場合は、エクスポートしたソースコードや正確なデプロイ先情報（クラウド、リージョン、ビルド設定、必要なサービス）を含めて、運用が元のプロジェクトワークスペースに依存せずにアプリを再現できるようにしてください。要件が変わるたびにパッケージを更新する簡単なリズムを決め、ランブックが現実と乖離しないようにします。