Agent-almanac write-incident-runbook

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/ja/skills/write-incident-runbook" ~/.claude/skills/pjt222-agent-almanac-write-incident-runbook-ffd145 && rm -rf "$T"

manifest: i18n/ja/skills/write-incident-runbook/SKILL.md

source content

インシデントランブックの作成

インシデントの診断と解決を通じて対応者をガイドするアクション可能なランブックを作成する。

使用タイミング

繰り返し発生するアラートまたはインシデントの対応手順を文書化する場合
オンコールローテーションメンバー全体でインシデント対応を標準化する場合
明確な診断手順で平均解決時間（MTTR）を削減する場合
インシデント対応に関する新しいチームメンバー向けのトレーニング資料を作成する場合
エスカレーションパスとコミュニケーションプロトコルを確立する場合
属人的な知識を文書化されたドキュメントに移行する場合
アラートを解決手順にリンクする場合（アラートアノテーション）

入力

必須: インシデントまたはアラートの名前/説明
必須: 過去のインシデントデータと解決パターン
任意: 診断クエリ（Prometheus、ログ、トレース）
任意: エスカレーションの連絡先とコミュニケーションチャンネル
任意: 過去のインシデントのポストモーテム

手順

ステップ1: ランブックテンプレート構造を選択する

完全なテンプレートファイルは拡張例を参照。

インシデントの種類と複雑さに基づいて適切なテンプレートを選択する。

基本的なランブックテンプレート構造：

# [Alert/Incident Name] Runbook
## Overview | Severity | Symptoms
## Diagnostic Steps | Resolution Steps
## Escalation | Communication | Prevention | Related

高度なSREランブックテンプレート（抜粋）：

# [Service Name] - [Incident Type] Runbook

## Metadata
- Service, Owner, Severity, On-Call, Last Updated

## Diagnostic Phase
### Quick Health Check (< 5 min): Dashboard, error rate, deployments
### Detailed Investigation (5-20 min): Metrics, logs, traces, failure patterns
# ... (完全なテンプレートはEXAMPLES.mdを参照)

主要なテンプレートコンポーネント：

メタデータ: サービスオーナーシップ、重大度、オンコールローテーション
診断フェーズ: クイックチェック → 詳細調査 → 障害パターン
解決フェーズ: 即時の緩和 → 根本原因の修正 → 検証
エスカレーション: 基準と連絡先パス
コミュニケーション: 社内/社外テンプレート
防止策: 短期/長期のアクション

期待結果： 選択されたテンプレートがインシデントの複雑さに一致し、サービスの種類に適したセクションがある。

失敗時：

基本テンプレートから始めて、インシデントパターンに基づいて反復する
業界の例をレビューする（Google SREブック、ベンダーのランブック）
初回使用後のチームフィードバックに基づいてテンプレートを調整する

ステップ2: 診断手順を文書化する

完全な診断クエリと決定ツリーは拡張例を参照。

具体的なクエリを含む段階的な調査手順を作成する。

六ステップの診断チェックリスト：

サービスの健全性を確認: ヘルスエンドポイントチェックとアップタイムメトリクス

curl -I https://api.example.com/health  # Expected: HTTP 200 OK

up{job="api-service"}  # Expected: 1 for all instances

エラーレートを確認: 現在のエラーパーセンテージとエンドポイント別の内訳

sum(rate(http_requests_total{status=~"5.."}[5m]))
/ sum(rate(http_requests_total[5m])) * 100  # Expected: < 1%

ログを分析: LokiからのRecentエラーとトップエラーメッセージ

{job="api-service"} |= "error" | json | level="error"

リソース使用率を確認: CPU、メモリ、接続プールのステータス

avg(rate(container_cpu_usage_seconds_total{pod=~"api-service.*"}[5m])) * 100
# Expected: < 70%

最近の変更をレビュー: デプロイ、Gitコミット、インフラの変更
依存関係を確認: ダウンストリームサービスの健全性、データベース/APIのレイテンシ

障害パターン決定ツリー（抜粋）：

サービスが停止？ → すべてのPod/インスタンスを確認する
エラーレートが上昇？ → 特定のエラータイプを確認する（5xx、ゲートウェイ、データベース、タイムアウト）
いつ始まったか？ → デプロイ後（ロールバック）、緩やか（リソースリーク）、突然（トラフィック/依存関係）

期待結果： 診断手順が具体的で、期待値と実際の値を含み、対応者を調査に導く。

失敗時：

文書化する前に実際のモニタリングシステムでクエリをテストする
視覚的な参照のためにダッシュボードのスクリーンショットを含める
見逃されやすい手順のために「よくある間違い」セクションを追加する
インシデント対応者からのフィードバックに基づいて反復する

ステップ3: 解決手順を定義する

完全なコマンドとロールバック手順を含む5つの解決オプションはすべて拡張例を参照。

段階的なロールバックオプション付きの修復を文書化する。

5つの解決オプション（簡単な概要）：

デプロイのロールバック（最速）: デプロイ後のエラーの場合
```
kubectl rollout undo deployment/api-service
```
確認 → 監視 → 解決を確認する（エラーレート < 1%、レイテンシ正常、アラートなし）

リソースのスケールアップ: 高いCPU/メモリ、接続プールの枯渇の場合

kubectl scale deployment/api-service --replicas=$((current * 3/2))

サービスの再起動: メモリリーク、スタックした接続、キャッシュの破損の場合

kubectl rollout restart deployment/api-service

フィーチャーフラグ/サーキットブレーカー: 特定の機能エラーまたは外部依存関係の障害の場合

kubectl set env deployment/api-service FEATURE_NAME=false

データベース修復: データベース接続、遅いクエリ、プールの枯渇の場合

-- Kill long-running queries, restart connection pool, increase pool size

ユニバーサル検証チェックリスト：

エラーレート < 1%
レイテンシP99 < しきい値
スループットがベースライン
リソース使用量が健全（CPU < 70%、メモリ < 80%）
依存関係が健全
ユーザー向けのテストが合格
アクティブなアラートなし

ロールバック手順: 解決策が状況を悪化させる場合 → 一時停止/キャンセル → 元に戻す → 再評価する

期待結果： 解決手順が明確で、検証チェックを含み、各アクションのロールバックオプションを提供する。

失敗時：

複雑な手順のためにより細かい手順を追加する
マルチステッププロセスのためにスクリーンショットまたは図を含める
コマンドの出力を文書化する（期待値と実際の値）
複雑な解決手順のために別のランブックを作成する

ステップ4: エスカレーションパスを確立する

インシデントをいつどのようにエスカレートするかを定義する。

完全なエスカレーションレベルと連絡先ディレクトリのテンプレートは拡張例を参照。

即座にエスカレートするタイミング：

カスタマー向けの停止が15分以上
SLOエラーバジェットが10%以上消費された
データの損失/破損またはセキュリティ侵害が疑われる
20分以内に根本原因を特定できない
緩和の試みが失敗するか状況を悪化させる

5つのエスカレーションレベル：

プライマリオンコール（5分レスポンス）: 修正のデプロイ、ロールバック、スケールアップ（最大30分の単独作業）
セカンダリオンコール（15分後に自動）: 追加の調査サポート
チームリード（アーキテクチャ上の決定）: データベースの変更、ベンダーエスカレーション、1時間以上のインシデント
インシデントコマンダー（クロスチーム調整）: 複数チーム、カスタマーコミュニケーション、2時間以上のインシデント
エグゼクティブ（Cレベル）: 大きな影響（ユーザーの50%以上）、SLA違反、メディア/PR、4時間以上の停止

エスカレーションプロセス：

現在のステータス、影響、実施したアクション、必要な支援、ダッシュボードリンクを含めてターゲットに通知する
必要な場合のハンドオフ: タイムライン、アクション、アクセスを共有し、引き続き対応する
沈黙しない: 15分ごとに更新し、質問し、フィードバックを提供する

連絡先ディレクトリ: プラットフォーム/データベース/セキュリティ/ネットワークチーム、インシデントコマンダー、外部ベンダー（AWS、データベースベンダー、CDNプロバイダー）のロール、Slack、電話、PagerDutyのテーブルを維持する

期待結果： エスカレーションの明確な基準、連絡先情報へのすぐのアクセス、組織構造に合ったエスカレーションパス。

失敗時：

連絡先情報が最新であることを確認する（四半期ごとにテストする）
エスカレーションのタイミングの決定ツリーを追加する
エスカレーションメッセージの例を含める
各レベルのレスポンス時間の期待値を文書化する

ステップ5: コミュニケーションテンプレートを作成する

インシデントの更新のための事前作成されたメッセージを提供する。

すべての社内・社外テンプレートと完全なフォーマットは拡張例を参照。

社内テンプレート（Slack #incident-response）：

最初の宣言：

🚨 INCIDENT: [Title] | Severity: [Critical/High/Medium]
Impact: [users/services] | Owner: @username | Dashboard: [link]
Quick Summary: [1-2 sentences] | Next update: 15 min

進捗更新（15〜30分ごと）：

📊 UPDATE #N | Status: [Investigating/Mitigating/Monitoring]
Actions: [what we tried and outcomes]
Theory: [what we think is happening]
Next: [planned actions]

緩和完了：

✅ MITIGATION | Metrics: Error [before→after], Latency [before→after]
Root Cause: [brief or "investigating"] | Monitoring 30min before resolved

解決：

🎉 RESOLVED | Duration: [time] | Root Cause + Impact + Follow-up actions

誤報: 影響なし、フォローアップ不要

外部テンプレート（ステータスページ）：

最初: 調査中、開始時間、次の更新まで15分
進捗: 原因を特定（カスタマーフレンドリー）、修正を実装中、推定解決時間
解決: 解決時間、根本原因（シンプル）、期間、防止策

カスタマーメールテンプレート: タイムライン、影響の説明、解決策、防止策、補償（該当する場合）

期待結果： テンプレートがインシデント中の時間を節約し、一貫したコミュニケーションを確保し、対応者の認知負荷を軽減する。

失敗時：

会社のコミュニケーションスタイルに合わせてテンプレートをカスタマイズする
一般的なインシデントの種類でテンプレートを事前入力する
テンプレートを自動的に入力するSlackワークフロー/ボットを作成する
インシデントの振り返り中にテンプレートをレビューする

ステップ6: モニタリングにランブックをリンクする

完全なPrometheusアラート設定とGrafanaダッシュボードのJSONは拡張例を参照。

アラートとダッシュボードにランブックを統合する。

Prometheusアラートにランブックリンクを追加：

- alert: HighErrorRate
  annotations:
    runbook_url: "https://wiki.example.com/runbooks/high-error-rate"
    dashboard_url: "https://grafana.example.com/d/service-overview"
    incident_channel: "#incident-platform"

ランブックにクイック診断リンクを埋め込む：

サービス概要ダッシュボード
直近1時間のエラーレート（Prometheusの直接リンク）
最近のエラーログ（Loki/Grafana Explore）
最近のデプロイ（GitHub/CI）
PagerDutyのインシデント

Grafanaダッシュボードパネルを作成（すべてのインシデントランブックをオンコールとエスカレーション情報とともに一覧表示するマークダウンパネルでランブックリンクを表示）

期待結果： 対応者がアラートやダッシュボードから直接ランブックにアクセスでき、診断クエリが事前入力され、関連ツールへのワンクリックアクセスが実現する。

失敗時：

ランブックのURLがVPN/ログインなしでアクセス可能であることを確認する
複雑なGrafana/PrometheusリンクにはURL短縮サービスを使用する
リンクが壊れないように四半期ごとにテストする
頻繁に使用するランブックにブラウザのブックマークを作成する

バリデーション

よくある落とし穴

汎用的すぎる: 「ログを確認する」のような曖昧な手順のランブックはアクション可能でない。具体的に記述する。
古い情報: 古いシステムやコマンドを参照するランブックは役に立たなくなる。四半期ごとにレビューする。
検証手順なし: 検証なしの解決策は偽陽性につながる。常に「修正されたことを確認する方法」を含める。
ロールバック手順の欠如: すべてのアクションにロールバック計画が必要。対応者をより悪い状態に陥れない。
知識の前提: エキスパートのみのランブックは若いエンジニアを排除する。ローテーションで最も経験の浅い人を対象に書く。
オーナーシップなし: オーナーのいないランブックは古くなる。更新を担当するチーム/担当者を割り当てる。
認証の壁: VPN/SSO問題中にアクセスできないランブックは危機時には役に立たない。コピーをキャッシュするか公開Wikiを使用する。

Agent-almanac write-incident-runbook

インシデントランブックの作成

使用タイミング

入力

手順

ステップ1: ランブックテンプレート構造を選択する

ステップ2: 診断手順を文書化する

ステップ3: 解決手順を定義する

ステップ4: エスカレーションパスを確立する

ステップ5: コミュニケーションテンプレートを作成する

ステップ6: モニタリングにランブックをリンクする

バリデーション

よくある落とし穴

関連スキル