SREのドキュメント文化｜RunbookとPlaybookの書き方・運用方法を徹底解説

SRE実務プラクティス
2026.04.29

「あの手順、〇〇さんに聞かないとわからない」——その状態が続いている組織は、障害時に必ず詰まります。

深夜2時にアラートが鳴って、担当エンジニアがオンコールに応答する。でも手順書がないか古くて信用できないため、ゼロから調査を始めることになる。その間にもユーザーへの影響は拡大していく——このシナリオは、SREが整備されていないチームで何度も繰り返されます。

SREにおけるドキュメント文化の中核が、RunbookとPlaybookです。 適切に整備されたRunbook・Playbookは、障害対応時間を大幅に短縮し、オンコール担当者の精神的負荷を下げ、チームの知識を組織の資産として蓄積します。

この記事では、SREが実務で使えるRunbook・Playbookの書き方とその運用方法を解説します。

この記事でわかること
– RunbookとPlaybookの違い（どちらをいつ使うか）
– Runbookの書き方と実際に使えるテンプレート
– Playbookの書き方と障害シナリオ別の設計方法
– ドキュメントを陳腐化させない継続的な更新の仕組み
– よくある失敗パターンと現場での対策

前提条件: インシデント対応の基礎知識（インシデント対応フローの設計はこちら）や、ポストモーテムの書き方を知っているとより理解が深まります。

Two documents side by side - Runbook as a step-by-step checklist with numbered procedures and comman

RunbookとPlaybookの違い

SREのドキュメントを整備する際、最初に明確にしておくべきなのが「RunbookとPlaybookはどう違うのか」という点です。

Runbook（ランブック）とは

Runbookは手順書です。特定の操作・タスクを実行するための、具体的なコマンドやステップをまとめたドキュメントです。

  • 「EC2インスタンスを再起動する手順」
  • 「DBのスロークエリを調査するコマンド一覧」
  • 「デプロイをロールバックする手順」

これらはすべてRunbookです。「どう操作するか」に答えるドキュメントです。

Playbook（プレイブック）とは

Playbookは対応ガイドです。特定のアラートや障害シナリオに対して、「何を確認し・どう判断し・誰に連絡するか」の判断フローをまとめたドキュメントです。

  • 「エラーレートが5%を超えたときの対応フロー」
  • 「RDS接続エラーが多発したときのトリアージ手順」
  • 「決済サービスが応答しないときのエスカレーション判断基準」

これらはPlaybookです。「何が起きたとき何をすべきか」に答えるドキュメントです。

RunbookとPlaybookの比較

項目 Runbook Playbook
目的 操作手順の標準化 インシデント対応の判断支援
内容 具体的なコマンド・ステップ 確認ポイント・判断分岐・エスカレーション
使うタイミング 定常運用・障害対応中 アラート発火時・トリアージ段階
構造 順序あり（Step 1 → 2 → 3） 分岐あり（If A then X、If B then Y）
粒度 操作単位（細かい） シナリオ単位（大きい）
更新頻度 インフラ変更のたびに更新が必要 アラート設計・組織体制の変更時に更新

実際の障害対応では、Playbookが「次にRunbookのX番を実行する」と参照するという形で2つが連携します。

Well-structured Runbook template layout with title, purpose, prerequisites, step-by-step procedure w

Runbookの書き方

Runbookが必要な操作の選び方

すべての操作をRunbookにする必要はありません。以下の基準に当てはまる操作を優先します。

  • 繰り返し発生する: 月1回以上実行する
  • 誤操作リスクが高い: 本番への影響が大きい操作
  • 属人化している: 特定の人しか知らない
  • 時間がかかる: 手順が複雑で判断が必要

現場でよく見かける「Runbookを書くべき操作」の例を挙げます。

監視・アラート系
– CloudWatchアラームが発火したときの確認手順
– ログのフィルタリングとエラー原因の絞り込み方法
– X-Rayトレースで遅延の根本原因を特定する手順

インフラ操作系
– EC2インスタンスの再起動・停止・起動手順
– RDSのフェイルオーバー実行手順
– ECSサービスのデプロイとロールバック手順
– SSL/TLS証明書の更新手順

デプロイ・変更系
– アプリケーションのカナリアデプロイ手順
– フィーチャーフラグのON/OFF切り替え方法
– Terraformによるインフラ変更の実行手順

Runbookのテンプレート

実際に使えるRunbookのテンプレートを紹介します。

# [操作名] Runbook

## 概要
- **目的**: [この手順が何を実現するか1行で]
- **適用範囲**: [どの環境・サービスに適用するか]
- **所要時間**: [目安の作業時間]
- **最終更新**: YYYY-MM-DD
- **作成者**: [担当チーム]

## 前提条件

### 必要な権限
- [ ] AWSアカウントへのアクセス権（ロール: [ロール名]）
- [ ] [サービス名]へのAdmin権限

### 事前確認
- [ ] [確認事項1]
- [ ] [確認事項2]
- [ ] 作業対象の環境: [ ] staging / [ ] production

## 手順

### Step 1: [ステップ名]
[ステップの目的を1行で説明]

```bash
# コマンドの説明
aws [コマンド] --option value
```

**確認方法**: [このステップが成功したかどうかの確認方法]
**期待される出力**:
```
[期待される出力例]
```

### Step 2: [ステップ名]
...

## 完了確認

実施後、以下がすべて確認できれば作業完了です。

- [ ] [確認項目1]
- [ ] [確認項目2]
- [ ] CloudWatchダッシュボードでメトリクスが正常範囲内

## ロールバック手順

作業が失敗した場合または問題が発生した場合のロールバック手順。

### ロールバックStep 1
```bash
# ロールバックコマンド
```

## 注意事項 / やってはいけないこと

- ⚠️ [注意事項1]: [理由]
- ⚠️ [注意事項2]: [理由]

## 関連ドキュメント
- [関連Runbook名](リンク)
- [関連Playbook名](リンク)

Runbook執筆の5つのポイント

① コマンドはそのままコピペできる形で書く

「〇〇コマンドを実行する」ではなく、実際のコマンドを書きます。引数や環境変数も含めて、コピペすればそのまま動く形にすることが理想です。

# ❌ わかりにくい例
ECSサービスを再起動するコマンドを実行する

# ✅ 良い例
aws ecs update-service \
  --cluster production-cluster \
  --service api-service \
  --force-new-deployment \
  --region ap-northeast-1

② 期待される出力・正常状態を明記する

コマンドを実行した後「これが表示されれば成功」という確認方法を書きます。深夜に焦っている状態で「これで合ってるのか？」と迷う時間を排除します。

③ 「やってはいけないこと」を書く

正しい手順だけでなく、よくあるミスや実行してはいけない操作を明記します。特に、本番データに影響するコマンドは枠組みで警告します。

④ 所要時間の目安を書く

「Step 2のコマンドは完了まで5〜10分かかる」と書くだけで、担当者は余計な焦りなく待てます。タイムアウトの目安も合わせて記載します。

⑤ 最終更新日と作成者を必ず書く

Runbookの最大の敵は「古い情報」です。最終更新日が1年以上前のRunbookは信頼できません。更新日を常に見えるところに書くことで、利用者が鮮度を判断できます。

Incident response Playbook as flowchart showing alert trigger at top, branching decision points with

Playbookの書き方

Playbookの設計方針

Playbookは「アラートが鳴ったとき、オンコール担当者が迷わず動ける」ことを目的に設計します。

設計の際に意識すべき点は3つです。

  1. 5分以内に次のアクションが決まること: Playbookを見た担当者が、5分以内に「調査を続けるか・エスカレーションするか・対処できるか」を判断できること
  2. 分岐を明確にすること: 「もし〇〇なら → △△する、そうでなければ → □□する」という形で判断ポイントを明示する
  3. RunbookへのリンクをPlaybookに埋め込む: 「対処が必要な場合は [RDSロールバックRunbook] を参照」のように、操作手順への参照を含める

Playbookのテンプレート

# [アラート名 / 障害シナリオ名] Playbook

## 概要
- **対象アラート**: [CloudWatchアラーム名 / PagerDutyポリシー名]
- **このPlaybookが対応するシナリオ**: [1〜2行で説明]
- **最終更新**: YYYY-MM-DD
- **オーナー**: [担当チーム]

## SLOへの影響
- **関連SLI**: [例: APIエラーレート]
- **SLOしきい値**: [例: エラーレート < 1%]
- **エラーバジェット消費速度**: [例: このアラートが30分続くと月次エラーバジェットの10%を消費]

## Step 1: 初動確認（目標: 5分以内）

### 1-1. 影響範囲の確認
以下を確認して、影響の大きさを把握します。

```bash
# エラーレートの現在値を確認
aws cloudwatch get-metric-statistics \
  --namespace AWS/ApplicationELB \
  --metric-name HTTPCode_Target_5XX_Count \
  ...
```

| 確認項目 | 確認方法 | 正常値 |
|---------|---------|--------|
| エラーレート | CloudWatchダッシュボード | < 1% |
| 影響ユーザー数 | [Datadogリンク] | - |
| 対象サービス | [サービスマップ] | - |

### 1-2. 自己回復の確認
**5分待って自然に回復している場合**: 引き続き監視し、ポストモーテム（軽微）を作成する。
**回復していない場合**: Step 2へ進む。

## Step 2: 原因の切り分け（目標: 15分以内）

### 判断フロー

```
エラーが継続中
├── ALBが5xxを返している?
│   ├── YES → [ECSターゲットヘルス確認] → Step 2-A
│   └── NO  → アプリレイヤーを確認 → Step 2-B
│
└── RDSへの接続エラーがある?
    ├── YES → [RDS調査Playbook] を参照
    └── NO  → ログを調査 → Step 2-C
```

### Step 2-A: ECSターゲットヘルス確認

```bash
# ターゲットグループのヘルス確認
aws elbv2 describe-target-health \
  --target-group-arn [TARGET_GROUP_ARN]
```

ターゲットが **unhealthy** の場合 → [ECSタスク再起動Runbook](/runbooks/ecs-task-restart/) を実行
ターゲットが **healthy** なのに5xxが出る場合 → Step 2-B へ

### Step 2-B: アプリケーションログ調査

```bash
# CloudWatch Logs Insightsでエラーログを検索
fields @timestamp, @message
| filter @message like /ERROR/
| sort @timestamp desc
| limit 50
```

## Step 3: 対処・エスカレーション判断

### 自分で対処できる場合
- [原因A] → [対処RunbookへのリンクA]
- [原因B] → [対処RunbookへのリンクB]

### エスカレーションが必要な場合

以下のいずれかに当てはまる場合は、即座にエスカレーションします。

- [ ] 影響ユーザー数が1,000人以上
- [ ] エラーレートが10%を超えている
- [ ] 15分以内に原因が特定できない
- [ ] データ損失・セキュリティインシデントの可能性がある

**エスカレーション先**:
- SREリード: [Slackハンドル] / 電話: [緊急連絡先]
- アプリチームリード: [Slackハンドル]
- マネージャー（SEV1時のみ）: [Slackハンドル]

## Step 4: 復旧確認

以下がすべてGREENになれば復旧完了です。

- [ ] エラーレート < 1%（5分間継続）
- [ ] CloudWatchアラームがOK状態に戻った
- [ ] 影響を受けたユーザーへの通知が完了した

## 関連ドキュメント
- [ECSタスク再起動Runbook](/runbooks/ecs-task-restart/)
- [RDS調査Playbook](/playbooks/rds-connection-error/)
- [インシデント対応フロー](/incident-response-flow-design/)

PlaybookにMermaidフロー図を使う

判断フローが複雑な場合、テキストより図の方が直感的に理解できます。

graph TD

    A["🔔 アラート発火
（エラーレート > 5%）"] --> B["影響範囲確認
5分以内"]

    B --> C{自然回復?}

    C -->|YES| D["監視継続
軽微なポストモーテム作成"]

    C -->|NO| E["原因の切り分け
15分以内"]

    E --> F{ALBが5xxを返している?}

    F -->|YES| G["ECSターゲットヘルス確認
Runbook参照"]

    F -->|NO| H["アプリログ調査
Logs Insights"]

    G --> I{15分で解決できるか?}

    H --> I

    I -->|YES| J["対処実施
Runbook実行"]

    I -->|NO| K["🚨 エスカレーション
SREリードに連絡"]

    J --> L["復旧確認
ポストモーテム作成"]

    K --> L

ドキュメントを陳腐化させない仕組み

Runbook・Playbookの最大の問題は「最初だけ書いて更新されなくなる」ことです。古いRunbookはないRunbookより悪い——誤ったコマンドを実行して障害を悪化させるリスクがあるからです。

更新タイミングを明確にルール化する

以下のイベントが発生したときは、必ず対応するRunbook・Playbookを見直すルールを設けます。

イベント 対応するドキュメント
インフラ構成の変更（TerraformのPRマージ時） 影響を受けるRunbook
新しいアラートの追加 対応するPlaybookの新規作成
ポストモーテムのアクションアイテム 関連するRunbook・Playbookの改善
オンコール担当者から「手順が古い」というフィードバック 即日更新
半年ごとの定期レビュー 全ドキュメントのレビュー

Runbookのレビューをコードレビューに組み込む

インフラをコードで管理している場合（IaC）、インフラ変更のPRにRunbookの更新を含めるルールを設けます。

PRの説明テンプレート例:

## 変更内容
- ECSのコネクションプールサイズを100→300に変更

## ドキュメント更新
- [x] ECSタスク設定変更Runbookを更新した
- [ ] 関連するPlaybookへの影響を確認した

このルールを設けることで、「コードは更新されたがRunbookは古いまま」という状態を防げます。

実際の障害対応中にRunbookを更新する

障害対応中に「Runbookと手順が違う」と気づいたとき、その場でRunbookを更新します。「後でまとめて更新しよう」は実行されません。

インシデント対応のSlackチャンネルに #runbook-update というハッシュタグを使って「このRunbookを更新すべき」というメモを残し、ポストモーテムのアクションアイテムとして管理する運用も有効です。

「使われたかどうか」を計測する

ドキュメント管理ツール（Confluence・Notion・GitHubなど）のページビューを定期的に確認します。6ヶ月以上アクセスされていないRunbookは、「本当に必要か」を見直す対象にします。

使われていないRunbookには2つの可能性があります。
– その操作が自動化されている → Runbookをアーカイブして問題ない
– 存在を誰も知らない → 可視性を上げるか、場所を整理する必要がある

Three warning signs of documentation failure - outdated runbook with

よくある失敗パターンと対策

失敗1: コマンドが環境依存で動かない

「古いRunbookのコマンドをコピペしたらエラーになった」は現場でよく起きます。

原因: ARN・エンドポイント・環境変数が古い・またはハードコードされている

対策: コマンド内の環境依存部分を変数として明示します。

# ❌ ハードコードされていて動かない例
aws ecs update-service \
  --cluster arn:aws:ecs:ap-northeast-1:123456789012:cluster/prod-cluster \
  --service api-service

# ✅ 変数を明示した例
# 事前に設定する変数:
CLUSTER_ARN="$(aws ecs list-clusters | jq -r '.clusterArns[] | select(contains("prod"))')"
SERVICE_NAME="api-service"

aws ecs update-service \
  --cluster $CLUSTER_ARN \
  --service $SERVICE_NAME \
  --force-new-deployment

失敗2: Playbookのエスカレーション先が古い

「連絡先に電話したら別の人が出た」「Slackハンドルが変わっていた」という事態は障害時のストレスを激増させます。

対策: エスカレーション先は「役職名」で書き、個人名は補足にします。PagerDutyのオンコールスケジュールに連動させることが理想です。

# ❌ 個人名で書く（人事異動で即座に陳腐化）
エスカレーション先: 田中さん（@tanaka）

# ✅ 役職名で書き、動的に確認できるようにする
エスカレーション先: SREオンコールリード（PagerDutyスケジュール: [リンク]）
※バックアップ: @sre-team Slackチャンネルに投稿

失敗3: RunbookとPlaybookが混在して区別できない

「これRunbookなのかPlaybookなのかわからない」というドキュメントが増えると、障害時に使いにくくなります。

対策: ドキュメントの命名規則と保存場所を統一します。

ドキュメント構造の例（Confluenceの場合）:
SRE Documentation/
├── Playbooks/           ← アラート別・シナリオ別の対応ガイド
│   ├── ALB-5xx-spike.md
│   ├── RDS-connection-error.md
│   └── ECS-task-crash.md
│
├── Runbooks/            ← 操作手順書
│   ├── ecs-task-restart.md
│   ├── rds-failover.md
│   └── deploy-rollback.md
│
└── Architecture/        ← システム構成・設計ドキュメント

失敗4: Runbookが読まれない（存在を知らない）

書いたはずのRunbookが障害時に参照されず、担当者が手探りで対応していた——という状況は珍しくありません。

対策: CloudWatchアラームのDescription・PagerDutyのアラートメッセージにRunbook・PlaybookのURLを直接埋め込みます。

# CloudWatchアラームの説明にPlaybookのURLを含める
aws cloudwatch put-metric-alarm \
  --alarm-name "api-error-rate-critical" \
  --alarm-description "APIエラーレートが5%を超えました。\n対応Playbook: https://wiki.example.com/playbooks/alb-5xx-spike" \
  ...

アラートからワンクリックでPlaybookにアクセスできる状態にすることで、「Runbookを探す」という Toil を排除できます。

失敗5: Runbookが「完璧主義」になって書けない

「ちゃんとしたRunbookを書かなければ」という意識が高すぎると、Runbookがいつまでも作られません。

対策: 最初は箇条書きレベルでも良い。「完璧なRunbook」より「存在するRunbook」の方が価値があります。

Runbookの成熟度を段階的に定義することも有効です。

レベル 内容 目標
Lv.0 Runbookなし –
Lv.1 操作ステップの箇条書き 最初の1週間
Lv.2 コマンド・期待出力・注意点 実際に使って改善
Lv.3 ロールバック手順・エラーケース対応 3回使った後
Lv.4 自動テスト・定期検証の仕組みあり 成熟した状態

まずLv.1を目標に着手し、実際に使いながら育てていく姿勢が重要です。

AWSでのRunbook実装例

AWSを使っている環境では、RunbookをAWS Systems Manager Automation（SSM Automation）でコード化することで、人手を介さずに実行できるようになります。

SSM AutomationでRunbookを自動化する

Systems Manager Automationを使うと、手動で実行していたRunbookのステップを自動化できます。

# SSM Automation DocumentでEC2再起動Runbookを自動化
description: EC2インスタンスの安全な再起動手順
schemaVersion: "0.3"
parameters:
  InstanceId:
    type: String
    description: "再起動するEC2インスタンスID"
mainSteps:
  - name: verifyInstanceRunning
    action: aws:waitForAwsResourceProperty
    inputs:
      Service: ec2
      Api: DescribeInstances
      InstanceIds:
        - "{{InstanceId}}"
      PropertySelector: "$.Reservations[0].Instances[0].State.Name"
      DesiredValues:
        - running

  - name: stopInstance
    action: aws:changeInstanceState
    inputs:
      InstanceIds:
        - "{{InstanceId}}"
      DesiredState: stopped

  - name: startInstance
    action: aws:changeInstanceState
    inputs:
      InstanceIds:
        - "{{InstanceId}}"
      DesiredState: running

  - name: verifyRunning
    action: aws:waitForAwsResourceProperty
    inputs:
      Service: ec2
      Api: DescribeInstances
      InstanceIds:
        - "{{InstanceId}}"
      PropertySelector: "$.Reservations[0].Instances[0].State.Name"
      DesiredValues:
        - running

このSSM Automation Documentをベースに、CloudWatchアラームのアクションと連携させると、「アラート発火 → 自動でRunbookが実行される」という形で完全自動化できます。

SREドキュメント文化を組織に根付かせるには

Runbook・Playbookの書き方を知っていても、「チームとして継続的に整備する文化」がなければ形骸化します。

ドキュメント整備をオンコールの一部にする

オンコール担当者の責務として、「オンコール期間中に1つ以上のRunbook/Playbookを改善する」というルールを設けます。

オンコールの引き継ぎ時に以下を確認するテンプレートを作ることも有効です。

オンコール引き継ぎチェックリスト:
- [ ] 先週のアラート発火履歴を確認した
- [ ] 使ったRunbookは最新の状態に更新した
- [ ] 新しいアラートへのPlaybookを作成した（未作成があれば）
- [ ] エスカレーション先の連絡先を確認した

ポストモーテムからRunbookを生む

ポストモーテムのアクションアイテムに「〇〇のRunbookを作成する」「△△のPlaybookを更新する」を含めることで、障害のたびにドキュメントが改善されるサイクルが生まれます。

graph LR

    A["障害発生"] --> B["Playbook参照
で対応"]

    B --> C["ポストモーテム
実施"]

    C --> D["アクションアイテム:
Runbook/Playbook改善"]

    D --> E["Runbook/Playbook
更新"]

    E --> A

このサイクルが回り始めると、「障害が起きるたびにドキュメントが改善される」という状態になります。これがSREにおけるドキュメント文化の理想形です。

まとめ

SREのドキュメント文化のポイントをまとめます。

  • RunbookとPlaybookは役割が違う: Runbookは「どう操作するか」、Playbookは「何が起きたとき何をすべきか」に答えるドキュメント
  • Runbookはコピペできる具体性で書く: 曖昧な説明はなく、実行できるコマンド・期待される出力を含める
  • Playbookは判断フローを明確にする: 5分以内に次のアクションが決まる構造にする
  • 陳腐化させない仕組みを作る: インフラ変更・ポストモーテム・定期レビューとセットでドキュメントを更新する
  • アラートにPlaybookのURLを埋め込む: 障害時に「Runbookを探す」という Toil を排除する
  • 完璧を求めず始める: Lv.1の箇条書きから始めて、使いながら育てる

Runbook・Playbookの整備は、最初は手間に感じます。しかし、1本のRunbookが深夜の障害対応を30分短縮できるなら、その投資は十分に回収できます。まず1本、書いてみることから始めましょう。

インシデント対応・ドキュメント整備・SLO運用を体系的に学びたい方は、Udemyコース「AWS×SRE入門〜CloudWatchで学ぶ監視設計の基礎〜」で実践的に学べます。CloudWatchアラームと連携したRunbook設計の演習も含まれています。

Udemyコース「AWS×SRE入門」を見てみる

関連記事
– インシデント対応フローの設計｜検知から復旧・振り返りまでSRE流に解説
– ポストモーテムの書き方完全ガイド｜blameless文化を現場に根付かせる5つのポイント
– オンコール設計のベストプラクティス｜疲弊しない体制の作り方をSRE視点で解説
– Toilとは何か？SREがToil削減に取り組む方法

コメント

タイトルとURLをコピーしました