runbook-generator

runbook-generator skill の概要

runbook-generator ができること

runbook-generator は、デプロイ、インシデント対応、メンテナンス、ヘルスチェック、ロールバックの手順書が必要なサービス向けに、運用 Runbook のドラフトを作成するためのエンジニアリング skill です。Python ヘルパースクリプト scripts/runbook_generator.py が含まれており、サービス名、オーナー、環境をもとに構造化された Markdown の Runbook を生成できます。さらに references/runbook-templates.md には、デプロイ、インシデント、データベースメンテナンス、情報の陳腐化検知、検証に関する、より充実したパターンが用意されています。

DevOps、SRE、テクニカルライティングに向いているケース

runbook-generator skill は、サービス運用ドキュメントの一貫した出発点が必要なプラットフォームチーム、SRE、DevOps エンジニア、テクニカルライターに適しています。特に、新しいサービスを本番投入する前、オンコール担当者向けの基本的な手順書が必要なとき、または複数チームがばらばらの形式で Runbook を書いているときに役立ちます。

テクニカルライティングの観点では、単にページを素早く生成できることだけが価値ではありません。この skill は、ライターがエンジニアに確認すべき実務的な質問を整理するための構造を提供します。たとえば、オーナーシップ、アクセス権、デプロイ前後の確認、ロールバックの判断条件、エスカレーション経路、検証手順、レビュー頻度などです。

汎用プロンプトとの違い

汎用的な AI プロンプトでも、見た目の整った Runbook は生成できるかもしれません。しかし、運用上重要な詳細が抜け落ちるリスクがあります。runbook-generator はより実務に寄った設計です。標準的な運用セクションを備えた再利用可能な CLI の骨組みと、ステージングでのドライラン、明示的なロールバック条件、スモークテスト、四半期ごとの検証、デプロイ設定や CI ファイル変更時の陳腐化検知といった、実際の Runbook で問題になりやすい観点を示すリファレンスファイルを提供します。

導入前に考慮すべき点

この skill は、インフラ、サービス間の依存関係、CI/CD システム、監視ダッシュボード、シークレット管理ツールを自動で検査するものではありません。生成される出力は足場であり、そのまま承認済みの本番運用手順になるわけではありません。サンプルコマンドは実際のものに置き換え、実在するダッシュボードやアラートを追加し、ロールバック手順を検証し、オンコール用途として公開する前にステージングで手順をテストしてください。

runbook-generator skill の使い方

runbook-generator のインストールと最初に確認するファイル

Claude skills 環境にこの skill をインストールするには、次のコマンドを使います。

npx skills add alirezarezvani/claude-skills --skill runbook-generator

利用を前提にする前に、以下のソースファイルを確認してください。

• SKILL.md — 機能概要、クイックスタート、推奨ワークフロー。
• scripts/runbook_generator.py — 実際の CLI ジェネレーターとデフォルトの Markdown セクション。
• references/runbook-templates.md — デプロイ、インシデント対応、データベースメンテナンス、陳腐化検知、四半期検証の追加テンプレート。

このリポジトリには、この skill 専用の独立した README やメタデータファイルは含まれていないようです。そのため、まず読むべき重要なファイルはこの 3 つです。

runbook-generator の基本的な使い方

スクリプトは Runbook を stdout に出力することも、ファイルに書き出すこともできます。

python3 scripts/runbook_generator.py payments-api
python3 scripts/runbook_generator.py payments-api --owner platform --output docs/runbooks/payments-api.md

インストールしたバージョンのスクリプトが環境引数をサポートしている場合は、曖昧な「production/staging」前提を避けるためにそれを指定してください。サポートしていない場合は、生成された Markdown をすぐに編集し、環境を手動で明記します。通常、生成されるセクションには、概要、前提条件、起動・停止手順、ヘルスチェック、デプロイチェックリスト、ロールバック、インシデント対応、エスカレーション、検証メタデータが含まれます。

運用に必要な具体情報をプロンプトに入れる

弱い依頼の例は次のとおりです。

Generate a runbook for payments-api.

より有効な runbook-generator の使い方は、次のような依頼です。

Use runbook-generator to create a production runbook for payments-api. Owner is Platform Payments. Runtime is Kubernetes on EKS. Deployment is via GitHub Actions and Helm. Health endpoint is /healthz. Logs are in Datadog, traces in Honeycomb, alerts in PagerDuty service payments-api-prod. Include rollback triggers for elevated 5xx rate, p95 latency over 800 ms, failed migrations, or payment authorization errors. Add placeholders where I need to confirm exact commands.

このように指定すると、skill は汎用的なコマンドを作り込むのではなく、実際の運用判断に沿って足場を組み立てやすくなります。

生成後に推奨される作業フロー

まず初稿を生成し、その後サービスオーナーと一緒に編集します。すべてのサンプルコマンドを検証済みのコマンドに置き換え、期待される出力を追加し、ダッシュボードやアラート名へのリンクを入れ、エスカレーション先を定義してください。次に、ステージングで手順をドライランします。起動、停止、デプロイ、ヘルスチェック、ロールバックを実際に確認します。最後に Last verified の日付を追加し、references/runbook-templates.md のチェックリストを使って四半期ごとのレビューを予定に入れます。

runbook-generator skill FAQ

runbook-generator だけで本番 Runbook として十分ですか？

それだけでは不十分です。runbook-generator は構造化されたベースラインを作成しますが、本番対応として十分かどうかは、サービス固有の詳細が検証されているかに依存します。本番 Runbook には、実際のコマンド、アクセス前提、既知の障害モード、ロールバック判断点、ダッシュボードへのリンク、アラートルーティング、エスカレーション責任者、テスト済みの期待出力を含めるべきです。

この skill を使わない方がよい場合は？

安全性が極めて重要な作業、コンプライアンス要件が重い作業、高リスクなデータベース操作については、これだけを唯一の情報源として使わないでください。データベースメンテナンスのメモを組み立てる助けにはなりますが、マイグレーションの順序、ロックのリスク、バックアップ検証、リストア手順にはエンジニアによるレビューが必要です。また、ステージングでテストできないシステムの生成済み Runbook を公開することも避けてください。

インシデントテンプレートとはどう違いますか？

インシデントテンプレートは通常、トリアージ、緩和策、コミュニケーション、ポストモーテムのフォローアップに重点を置きます。runbook-generator skill はより広い範囲を扱います。起動、停止、ヘルスチェック、デプロイ、ロールバック、エスカレーションといった日常的な運用手順までカバーします。インシデント対応が多いサービスでは、生成された Runbook に references/runbook-templates.md のインシデント対応テンプレートを組み合わせるとよいでしょう。

初心者にも使いやすいですか？

はい。ただし、利用者が対象サービスを理解しているか、理解している人にヒアリングできることが前提です。初心者にとって、明確な構造は大きな助けになります。一方で、デプロイコマンド、オブザーバビリティ関連リンク、重大度ルール、ロールバック条件を埋めるには支援が必要になる場合があります。この skill は、自律的なインフラ専門家としてではなく、ガイド付きチェックリストとして使うのが最適です。

runbook-generator skill を改善する方法

出力を依頼する前に runbook-generator への入力情報を整える

品質を大きく左右するのは、元になる事実情報の質です。runbook-generator を実行する前に、次の情報を集めてください。

• サービス名、オーナー、Slack チャンネル、エスカレーション経路。
• 環境、ランタイム、デプロイツール、CI/CD ワークフロー。
• ヘルスエンドポイント、スモークテスト、ダッシュボード、アラート名。
• 依存関係の一覧: データベース、キュー、API、キャッシュ、外部サービス。
• ロールバック方法、直近の正常リリースの参照元、ロールバック条件。
• 最近のインシデントや既知の障害モード。

これらの情報があると、ドラフトが汎用的な運用ページになってしまうことを防げます。

プレースホルダーを検証可能な手順に置き換える

よくある失敗は、「ログを確認する」「メトリクスを監視する」「必要ならロールバックする」といった曖昧な手順です。これらを実行可能な指示に変換します。

• 「ログを確認する」ではなく、正確なログクエリやダッシュボードリンクを書く。
• 「スモークテストを実行する」ではなく、コマンドと期待されるレスポンスを列挙する。
• 「エラーが発生したらロールバックする」ではなく、しきい値と時間範囲を定義する。
• 「オーナーに連絡する」ではなく、PagerDuty service、Slack チャンネル、バックアップチーム名を明記する。

Runbook が本当に役立つのは、オンコール担当者がプレッシャーのかかる状況でも推測せずに従える状態になっているときです。

デフォルトの骨組みをテンプレートで拡張する

初稿を作成したら、サービスの必要に応じて references/runbook-templates.md を使い、内容を深めます。デプロイ頻度が高いサービスでは、デプロイ前チェック、成果物の検証、スモークテスト、コミュニケーションメモを追加します。インシデント対応では、最初の 5 分のトリアージ、診断に使う情報源、緩和策の選択肢、ポストモーテムでの対応を追加します。データベース作業では、バックアップ検証、ロックリスクの注意点、実行順序、リストア確認を加えます。

ステージング検証と実インシデントの後に更新する

優れた Runbook は、使われることで改善されます。ステージングでドライランした後は、壊れているコマンド、不足している権限、不明確な期待出力、時間に関する誤った前提を更新してください。インシデントの後には、対応者が実際に必要とした情報を追加します。たとえば、より速く診断できるリンク、より明確な重大度マッピング、より安全な緩和手順、より適切なロールバックしきい値です。Last verified フィールドを最新に保ち、デプロイ設定、CI パイプライン、スキーマ、ランタイム環境ファイルが変更されたときは Runbook を見直してください。