runbook-writer

ランブック作成スキル

サービス、インシデントの種類、デプロイ手順に関する運用ランブックを作成します。対象システムを使ったことがないオンコールエンジニアでも、緊急時に手順に従えるように構成します。

必要な入力

以下の情報が提供されていない場合は、確認してください。

• ランブックの目的（例：決済サービスのデプロイ、データベースのフェイルオーバーへの対応、API キーのローテーション）
• ランブックの種類（デプロイ／インシデント対応／メンテナンス／災害復旧）
• システム／サービス名とその役割（簡単な説明）
• 対象者（新任のオンコールエンジニア／経験豊富な SRE／DevOps チーム）
• 技術スタック（該当する場合。例：Kubernetes、AWS RDS、Node.js）
• 監視ツール（例：Grafana、Datadog、CloudWatch、Splunk。手順内で特定のダッシュボードやアラートへのリンクを示すために使用します）
• 主要な環境情報（例：Kubernetes クラスター名、AWS アカウント／リージョン、関連する名前空間やリソース名。正確なコマンドを記載できるよう、該当する情報を貼り付けてください）

出力形式

---

ランブック： [ランブックのタイトル] サービス： [サービス名] 種類： [デプロイ／インシデント対応／メンテナンス／災害復旧] 最終更新日： [今日の日付を YYYY-MM-DD 形式で挿入] 担当者： [チームまたは担当者] 重大度： [P1／P2／P3 — インシデントの場合]

---

概要

このランブックの対象： [このランブックで扱うシナリオを1～2文で説明]

このランブックを使用するタイミング：

• [具体的なトリガー条件 1 — 例：PagerDuty アラート：high-error-rate-payment-service]
• [具体的なトリガー条件 2 — 例：main への PR マージ後にデプロイが必要]

完了までの推定時間： [X分／結果に応じてX～Y分]

正しく完了できなかった場合の影響： [例：決済処理の低下／データ損失のリスク／ユーザーがロックアウトされる]

---

前提条件

必要なアクセス権：

• [システム／ツールへのアクセス — 例：AWS Console：production-account]
• [認証情報 — 例：vault read secret/payment-service]
• [必要に応じて VPN／踏み台サーバーへのアクセス]

必要なツール：

• [ツール名とバージョン — 例：kubectl v1.28+]
• [CLI またはダッシュボード名]

開始前の確認事項：

• [前提条件の確認 — 例：Grafana で現在のデプロイが正常であることを確認]
• [事前の対応 — 例：作業を開始することを #ops-live で告知]

---

手順

すべての手順に番号を付けてください。正確なコマンドを使用してください。ツール名やフラグを言い換えないでください。

手順 1：[操作名] [何を行うか、またその理由を1文で説明]

# Exact command
[command here]

期待される出力： [成功した場合に表示される内容] 失敗した場合： [確認すべき正確なエラーメッセージ] → [対応方法、または「トラブルシューティング」を参照]

手順 2：[操作名] [手順 1 と同じ形式]

手順 3：確認 主要な手順の後には、必ず確認手順を含めてください。

[verification command]

期待される状態： [このランブックの完了後に正常なシステムがどのような状態か]

---

ロールバック

問題が発生した場合に、この手順を取り消す方法：

手順 R1：[ロールバック操作]

[rollback command]

ロールバックの確認： [ロールバックの成功を確認するコマンド]

---

トラブルシューティング

症状	考えられる原因	解決方法
[エラーメッセージまたは確認できる症状]	[発生する理由]	[具体的な修正方法または次の手順]
[別の症状]	[原因]	[解決方法]

---

エスカレーション

このランブックで問題が解決しない場合：

条件	連絡先	方法
[例：10分経過しても DB が利用できない]	[DBA のオンコール担当者]	[PagerDuty ポリシー：db-oncall]
[例：決済プロバイダーから応答がない]	[ベンダーの連絡先]	[1Password の連絡先：vendor-escalation]

エスカレーションの前に、必ず [tool] のインシデントタイムラインを更新してください。

---

手順完了後のチェックリスト

ランブックの完了後：

• 結果とともに #ops-live で完了を告知する
• インシデントチケット／デプロイログを更新する
• 監視ダッシュボードでアラートが解消されたことを確認する
• このランブックの不備が判明した場合は、今すぐ更新する（編集手順へのリンク）

---

品質チェック

• 各ステップに正確なコマンドが記載されていること（「デプロイスクリプトを実行する」などとしない）
• 各ステップに期待される出力が記載され、エンジニアが成功したかどうかを確認できること
• 各ステップの失敗時の手順が明確であること（「失敗した場合は調査する」などとしない）
• ロールバック手順が完全で、単独でテストできること
• エスカレーション表に「[Team name]」だけのセルがないこと。各行には実際の連絡先を記載するか、[FILL IN: on-call rotation link] と明示すること
• ロールバックのセクションに具体的なコマンドが少なくとも1つ含まれていること（「[rollback command]」というプレースホルダーのままにしない）
• このシステムに触れたことがない人でもランブックに従えること

使用例

• 「[service] のデプロイ用ランブックを作成する」
• 「[alert type] のインシデント対応ランブックを作成する」
• 「[procedure] のランブックが必要です」
• 「[X] の運用手順を文書化する」
• 「[scenario] の運用プレイブックを作成する」

アンチパターン

• 「デプロイスクリプトを実行する」のような曖昧なアクションをステップとして記載しないこと。各ステップには正確なコマンドを含めること
• ロールバックのセクションをプレースホルダーのままにしないこと。テスト済みのロールバック手順がないランブックは不完全で危険です
• 各ステップの期待される出力を省略しないこと。記載がなければ、オンコールエンジニアはステップが成功したかどうかを判断できません
• エスカレーション先を「[Team name]」と記載しないこと。各行には実際の連絡先を記載するか、記入が必要であることを明示すること
• 読者がシステムを知っていると想定しないこと。初めて触れる人向けに記述すること