Statuspage APIの障害更新文をClaude Codeで下書きし、公開前に照合する

Atlassian Statuspageの更新文は、障害の最中に何度も書くことになります。急いで書くほど、時刻や影響範囲が手元のメモとずれます。この記事では、時系列メモを唯一の正として、Claude Codeに更新文を下書きさせ、メモと突き合わせて人が承認してから、Statuspage APIで投稿する流れを組みます。

個別のお知らせ文と想定問答はClaudeで障害のお知らせ文とサポート想定問答を作る、障害ステータスの読み方はClaude障害の確認方法にあります。ここで扱うのは、ステータスページ側の更新を続けるための下書きと照合、そしてAPIへの流し込みです。

更新文は状態ごとに役割が違う

Statuspageのインシデントは、管理画面で4つの状態のどれかを持ちます。更新のたびに状態を選び、短いメッセージを添える作りです。

状態の説明はStatuspageのヘルプにある定義です。ここから、Claudeに頼む文面の中身が決まります。

時系列メモを唯一の正にする

Claudeに更新文を直接頼む前に、材料を1枚のメモに固めます。更新文のたびに口頭やチャットの断片から書かせると、更新ごとに食い違いが出ます。

メモは時刻付きの箇条書きで、1行に1事実だけを書きます。事実と推測は列を分けます。

# incident-memo.md
| 時刻(JST) | 事実 | 出典 | 公開可否 |
|---|---|---|---|
| 14:02 | 決済APIの5xxが増加 | 監視アラート | 可 |
| 14:10 | 影響は注文確定のみ。閲覧は正常 | 担当者の確認 | 可 |
| 14:25 | 直前のデプロイが怪しい(未確認) | 担当者の推測 | 不可 |
| 14:40 | 原因はDB接続数の上限と判明 | 担当者の確認 | 条件付き |

「公開可否」の列が要点です。推測と未確認の行は不可にしておけば、下書きに混ざったときに照合で拾えます。

Claude Codeに常に守らせたい約束は、プロジェクトのCLAUDE.mdに書いておきます。次は例です。

## 障害更新文の作成ルール
- 材料は incident-memo.md の「公開可否」が「可」の行だけ。
- 「条件付き」の行は、書く前に確認を求める。
- メモに無い時刻・数値・原因を作らない。
- 1つの更新文は5文以内。次回更新の時刻を末尾に置く。
- 出力は draft.json の形式(status / body / evidence)で返す。

Claude Codeに下書きさせる

下書きは、更新ごとに状態を指定して頼みます。依頼文の例です。

incident-memo.md を材料に、いまの状態が Identified の
更新文を作ってください。draft.json に次の形で書き出します。
- status: investigating / identified / monitoring / resolved のどれか
- body: 公開する本文
- evidence: body の各文が根拠にした、メモの行(時刻)
メモの「可」の行以外は使わないでください。

evidenceを必ず出させるのがこの設計の核心です。本文の各文がメモのどの行に根拠を持つかを、Claude自身に書かせておきます。後の照合で、人が1文ずつメモに当たれます。

出力は例えば次のような形になります(形の例示であり、実際の返答ではありません)。

{
  "status": "identified",
  "body": "14:40に、注文確定の遅延の原因がデータベースの接続数の上限であると判明しました。現在、設定を見直して復旧作業を進めています。次回の更新は15:10までに行います。",
  "evidence": [
    {"sentence": 1, "memo_time": "14:40"},
    {"sentence": 2, "memo_time": "14:40"},
    {"sentence": 3, "memo_time": null, "note": "次回更新時刻は運用ルール由来"}
  ]
}

根拠がメモに無い文(上の3文目)は、memo_timeがnullになり、理由を添えさせます。運用ルール由来の文は許し、数値や原因が根拠なしに出てきたら差し戻す、という基準です。

公開前に事実を照合する

下書きができたら、投稿の前に照合を挟みます。照合も別の依頼として分けます。下書きをした会話の続きで「確認して」と頼むと、書いた本人が自分の文を追認するだけになりやすいからです。

照合で出す表の形はこのようにします。

| 文 | 本文の記述 | メモの行 | 判定 |
|---|---|---|---|
| 1 | 14:40に原因判明 | 14:40 DB接続数上限 | 一致 |
| 2 | 設定を見直して復旧作業 | (該当行なし) | 要確認 |
| 3 | 次回更新は15:10まで | (運用ルール) | 一致 |

「要確認」が1件でもあれば投稿しません。上の2文目のように、メモに無い対応内容が下書きに入ったときは、メモに事実を追記して再生成するか、文を削ります。

APIで投稿する

承認後の投稿は、Statuspage APIを呼ぶだけです。基本の取り決めは次のとおりです。

• ベースURLはhttps://api.statuspage.io/v1/で、HTTPSが必須です。
• 認証用のAPIキーは、管理画面の左下のアバターから「API info」を開くと取得できます。
• キーはAuthorization: OAuth <キー>ヘッダーで渡します。クエリパラメーターのapi_keyでも渡せますが、ログに残りやすいのでヘッダーのほうが無難です。
• 1つのAPIトークンは、60秒のローリングウィンドウで1リクエスト/秒に制限されます。超えると420または429が返ります。

新規インシデントの作成はPOST /pages/{page_id}/incidentsです。ボディのincidentには、name、status、body、component_ids、deliver_notificationsなどを指定できます。

# 環境変数にキーとページIDを置く(スクリプトに直書きしない)
export STATUSPAGE_KEY="..." PAGE_ID="..."
 
curl -sS -X POST \
  "https://api.statuspage.io/v1/pages/$PAGE_ID/incidents" \
  -H "Authorization: OAuth $STATUSPAGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"incident": {
        "name": "注文確定の遅延",
        "status": "investigating",
        "body": "14:02から注文確定が遅延しています。原因を調査中です。次回更新は14:30までに行います。",
        "component_ids": ["<コンポーネントID>"],
        "deliver_notifications": true
      }}'

2回目以降の更新は、同じインシデントに対するPATCH /pages/{page_id}/incidents/{incident_id}でstatusとbodyを送ります。置き換え用のPUTも同じパスにありますが、更新文の追加にはPATCHを使うと、送らない項目を壊しにくくなります。

投稿をスクリプトにまとめ、承認プロンプトを置いた例です。

#!/usr/bin/env bash
# post-update.sh <incident_id> draft.json
set -euo pipefail
jq -r '.body' "$2"
read -r -p "この本文を公開します。よければ yes: " ans
[ "$ans" = "yes" ] || { echo "中止"; exit 1; }
 
jq '{incident: {status: .status, body: .body}}' "$2" | curl -sS -X PATCH \
  "https://api.statuspage.io/v1/pages/$PAGE_ID/incidents/$1" \
  -H "Authorization: OAuth $STATUSPAGE_KEY" \
  -H "Content-Type: application/json" -d @-

ページIDとコンポーネントIDを先に控える

投稿に必要なpage_idは、APIキーを取得する管理画面の「API info」に表示されます。component_idsに入れるIDは、コンポーネントの一覧を返すエンドポイントで調べられます。

更新文が名指しする機能と、指定するコンポーネントの対応は、CLAUDE.mdか別の対応表に書いておきます。たとえば「注文確定」はこのIDの「決済」コンポーネント、というメモです。Claudeに下書きを頼むとき、この対応表も材料に渡します。照合の3手順目で、文面の機能名とcomponent_idsが食い違っていないかを、この表で確かめられます。IDを毎回その場で調べて貼ると、別のコンポーネントを指定して通知を出す事故につながります。

投稿後に読み戻して照合する

投稿が成功したら、GET /pages/{page_id}/incidents/{incident_id}で読み戻し、返ってきたincident_updatesのbodyとstatusが下書きと同じかを確かめます。応答にはincident_updatesの配列と、created_atやdisplay_atが含まれます。読み戻しの結果は、メモに「投稿済み」の行として追記しておくと、次の更新文を作るときの材料になります。

定型の文面はテンプレートに任せる

毎回変わらない冒頭の定型文は、Claudeに書かせず、Statuspageのインシデントテンプレートに置けます。テンプレートは名前、タイトル、本文、更新時の状態、通知の有無、対象コンポーネントを持ちます。管理画面の「Incidents」から「Templates」タブで作るか、POST /pages/{page_id}/incident_templatesで登録します。Claudeには、テンプレートの後ろに続く「今回固有の事実」の部分だけを書かせると、照合の対象が減ります。

更新の間隔と通知を決める

Statuspageのヘルプは、障害時の更新を30分ごと(状況に合う間隔でもよい)に出すよう勧めています。早く認め、頻繁に伝え、正確に伝える。チャネルごとに内容をそろえる。原因が他社にあっても自社の問題として扱う。この5点です。

更新間隔は、文面の末尾にある「次回更新」の約束とセットで運用します。約束した時刻にまだ伝える事実が無ければ、「進展はありません。次回は15:40までに更新します」という更新を出せます。この文もメモに「更新時刻の約束」として1行足しておくと、照合で拾えます。

通知については、2つの条件を押さえておきます。

• 通知を送る選択肢が出るのは、影響を受けるコンポーネントを1つ以上指定したときです。
• 同時に開けるインシデントは100件までです。

APIではdeliver_notificationsで通知の有無を切り替えられます。Resolvedの更新で購読者へ通知するかどうかは、組織の方針で決めてください。

つまずきやすい点

よくある質問

本文にHTMLは使えますか

Statuspageのヘルプによると、メッセージ欄は一部のHTMLタグを受け付けます。Claudeには、リンクや太字を使うときだけタグを書かせ、使えるタグはヘルプの「Add HTML tags in incident messages」で確かめてから指示に入れてください。

下書きと照合を同じ会話でやってはいけませんか

動きはしますが、書いた会話の文脈が残っていると、メモに無い内容まで「確かに書いた」と追認しがちです。照合は、本文とメモだけを渡した新しい会話で頼むほうが、食い違いを拾いやすくなります。

まとめ

更新文は、時系列メモを唯一の正にして下書きし、新しい会話で1対1に照合してから投稿するのが要点です。投稿後の読み戻しまで済ませると、次の更新の材料もそろいます。

障害が収まった後の顛末書は、障害報告書(顛末書)をClaudeで起こす手順にまとめています。APIキーを使った外部サービスの呼び出し方は、適格請求書発行事業者のWeb-APIをClaude Codeで呼ぶの構成が参考になります。