Claude Code本番障害対応ガイド: 検知から復旧・RCA・再発防止まで

Claude Codeを本番リポジトリで使うと、修正速度は上がります。反対に、承認を急いだ1コマンドで、秘密情報の漏えい、DB破壊、課金の急増、認証漏れが起きる余地も広がります。

この記事は、実在企業の障害報告ではありません。MasaがClaudeCodeLabの運用で行っている障害演習、記事更新、設定レビューをもとにした合成ケースです。金額や時刻は説明用ですが、事故の型はかなり現実的です。

初心者向けに用語もそろえます。インシデントは「サービスやデータに影響する事故」、封じ込めは「被害が広がらないよう一時停止すること」、RCAはroot cause analysisの略で「根本原因分析」、ロールバックは「直前の安全な状態へ戻すこと」です。

Claude Code自体の設定は公式のClaude Code settingsとhooks guideで確認してください。この記事では、公式仕様を前提に、本番障害の検知、封じ込め、診断、復旧、連絡、ポストモーテム、再発防止を一つの流れにします。

まず覚える障害対応フロー

障害対応で一番危ないのは、原因調査を急ぎすぎて被害を広げることです。Claude Codeに「直して」と投げる前に、次の順番を固定します。

段階	目的	Claude Codeに頼むこと
検知	何が壊れたかを確認	ログ、差分、監視アラートを要約させる
封じ込め	被害拡大を止める	危険なジョブ停止、キー失効、機能フラグOFF案を出させる
診断	直接原因を絞る	直近差分、デプロイ、DB変更、権限変更を並べる
ロールバック	安全な版に戻す	戻す対象、戻せないデータ、確認コマンドを明記させる
連絡	関係者の不安を減らす	状況、影響、次回更新時刻を短文にする
ポストモーテム	再発防止へ変える	RCA、検知漏れ、手順漏れ、期限付き対策を表にする
再発防止	同じ事故を潰す	settings.json、hooks、CI、レビュー観点を追加する

「調査してから止める」ではなく、「止めてから調査する」が原則です。特にAPI課金、秘密情報、個人情報、DB書き込みは、数分の遅れが被害範囲を変えます。

7つの具体的な事故パターン

ケース	起きること	初動	よくある落とし穴
APIキー漏えい	.envやログからキーが外部へ出る	キー失効、履歴確認、影響範囲の記録	git履歴から消したつもりで、CIログに残る
危険な削除	rm -rfや一括削除で必要ファイルが消える	作業停止、バックアップ確認、未追跡ファイルの棚卸し	git checkout .で未追跡ファイルは戻らない
force push	mainの他人のコミットを上書きする	push停止、reflog確認、保護ブランチ復旧	--force-with-leaseと--forceを混同する
DBマイグレーション失敗	カラム削除、全件更新、ロックで停止する	書き込み停止、バックアップ、読み取り専用化	staging未検証のSQLを本番に流す
API無限リトライ	外部APIやLLM APIを呼び続ける	プロセス停止、上限確認、請求アラート	「リトライ追加」が無制限ループになる
依存更新デプロイ失敗	起動時エラーやSSR失敗で503になる	前回デプロイへ戻す、lockfile差分確認	npm updateで意図せずmajor更新する
認証漏れ	管理APIや個人情報が未認証で見える	エンドポイント無効化、アクセスログ確認	「admin用」の言葉だけで認証要件を書かない

ケース1: APIキー漏えい

検知はGitHubのsecret scanning、クラウドの利用量アラート、請求画面、CIログから始まります。GitHubの仕組みは公式のsecret scanning documentationを見てください。

初動は原因調査ではなく失効です。漏れたキーを無効化し、新しいキーを発行し、CI/CDや本番環境のシークレットを差し替えます。次に、どこへ漏れたかを確認します。公開リポジトリ、PR差分、CIログ、チャット、エラー監視ツールの4か所を見ます。

git status --short
git diff --cached --name-only
git log --all -- .env .env.local
git grep -n "sk-" -- ':!node_modules' ':!dist'

落とし穴は、履歴削除を急いでさらにforce push事故を起こすことです。履歴を書き換えるなら、関係者に周知し、保護ブランチ、タグ、フォーク、CIキャッシュまで確認します。Claude Codeには「履歴を書き換えて」ではなく、「漏えい範囲、失効済み確認、履歴処理の選択肢、関係者への連絡文」を出させるほうが安全です。

ケース2: DBマイグレーション失敗

DB事故では、まず書き込みを止めます。アプリをメンテナンス表示にする、該当ジョブを止める、feature flagをOFFにする、DBユーザーを一時的に読み取り専用へ寄せる、の順で被害を止めます。

psql "$DATABASE_URL" -c "select now();"
psql "$DATABASE_URL" -c "\d users"
pg_dump "$DATABASE_URL" --schema-only > schema_before_repair.sql

復旧では「ロールバックできるコード」と「戻らないデータ」を分けます。コードは前回デプロイへ戻せても、削除済みデータはバックアップ、WAL、監査ログ、外部システムの再同期が必要です。Claude Codeには、SQLを実行させる前に、対象テーブル、影響行数、ロック時間、復元元、検証クエリを書かせます。

失敗例は、DELETE FROM users;のようなWHEREなしSQL、DROP COLUMNを含むdown migration、巨大テーブルへの同期インデックス作成です。これらはすべて「実行前に人間承認」にします。

ケース3: API無限リトライと課金急増

LLM APIや外部APIの事故は、ログ上はエラー処理に見えます。実際には「失敗するほど呼び続ける」状態になり、数時間で課金やレート制限に達します。封じ込めはプロセス停止、キュー停止、APIキー上限設定、アラート確認です。

以下は、任意のバッチ処理を試行回数と簡易コスト上限で止めるNode.jsラッパーです。incident-budget-runner.mjsとして保存し、node incident-budget-runner.mjs node batch.jsのように実行できます。

#!/usr/bin/env node
import { spawn } from "node:child_process";

const command = process.argv.slice(2);
const maxAttempts = Number(process.env.MAX_ATTEMPTS || 3);
const maxCostCents = Number(process.env.MAX_COST_CENTS || 200);
const costPerAttempt = Number(process.env.COST_PER_ATTEMPT_CENTS || 0);

if (command.length === 0) {
  console.error("usage: node incident-budget-runner.mjs <command> [...args]");
  process.exit(2);
}

let estimatedCost = 0;

for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
  const child = spawn(command[0], command.slice(1), {
    stdio: "inherit",
    shell: process.platform === "win32"
  });

  const exitCode = await new Promise((resolve) => {
    child.on("exit", (code) => resolve(code ?? 1));
  });

  estimatedCost += costPerAttempt;

  if (exitCode === 0) process.exit(0);
  if (estimatedCost >= maxCostCents) {
    console.error(`stopped: estimated cost ${estimatedCost} cents reached`);
    process.exit(1);
  }

  const delayMs = Math.min(1000 * 2 ** (attempt - 1), 10_000);
  await new Promise((resolve) => setTimeout(resolve, delayMs));
}

console.error(`failed after ${maxAttempts} attempts`);
process.exit(1);

Claude Code用の安全設定

公式ドキュメントでは、permissions.denyで機密ファイルの読み取りを拒否でき、hooksでツール実行前の検査を追加できます。まずは本番事故につながる操作をaskまたはdenyへ寄せます。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push --force *main*)",
      "Bash(git push -f *main*)",
      "Bash(rm -rf /*)",
      "Bash(rm -rf ~*)"
    ],
    "ask": [
      "Bash(git push*)",
      "Bash(rm*)",
      "Bash(npm install*)",
      "Bash(*migrate*)",
      "Bash(*deploy*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-danger.sh"
          }
        ]
      }
    ]
  }
}

hookスクリプトは、危険コマンドをexit code 2で止める形にします。

#!/usr/bin/env bash
set -euo pipefail

payload="$(cat)"
command="$(node -e 'const fs = require("fs"); const raw = fs.readFileSync(0, "utf8") || "{}"; const json = JSON.parse(raw); console.log(json.tool_input?.command || "");' <<< "$payload")"
blocked='(rm[[:space:]]+-rf[[:space:]]+(/|~)|git[[:space:]]+push[[:space:]].*(-f|--force)([[:space:]]|$)|DROP[[:space:]]+TABLE|TRUNCATE[[:space:]])'

if [[ "$command" =~ $blocked ]]; then
  echo "危険なコマンドをブロックしました: $command" >&2
  exit 2
fi

exit 0

連絡文とポストモーテムのテンプレート

障害中の連絡は短く、時刻入りにします。原因が未確定なら、未確定と書きます。

## 障害連絡
- 状態: 調査中 / 封じ込め済み / 復旧確認中
- 影響: 対象機能、対象ユーザー、開始時刻
- 現在の対応: 停止した処理、戻したデプロイ、確認中のログ
- 次の更新: YYYY-MM-DD HH:mm
- 問い合わせ窓口:

# ポストモーテム: [障害名]

## 概要
- 発生:
- 検知:
- 復旧:
- 影響:
- 重大度: P0/P1/P2/P3

## タイムライン
| 時刻 | 出来事 |
| --- | --- |
| HH:mm | |

## 原因
- 直接原因:
- 根本原因:
- 検知が遅れた理由:

## 再発防止
| 対策 | 担当 | 期限 |
| --- | --- | --- |
| | | |

ポストモーテム文化は、Google SREのPostmortem Cultureが参考になります。個人ブログでも小さな表を残すだけで、次回の判断が速くなります。

公開前に20分だけリハーサルする

この記事のテンプレートは、読むだけでは効果が半分です。小さなダミー障害を一つ作り、実際に時刻を入れて動かすと、自分の弱点が見えます。たとえば「APIキーがPRに出た想定」「DB migrationが失敗した想定」「バッチ処理がAPIを呼び続けた想定」の3つを、開発環境で順番に試します。

リハーサルでは、Claude Codeに本番コマンドを実行させる必要はありません。代わりに、検知メモ、封じ込め案、ロールバック案、連絡文、ポストモーテムの空欄を埋めさせます。人間は、バックアップの場所、APIキーの失効画面、デプロイの戻し方、アラートの通知先を確認します。ここで詰まった場所が、そのまま本番前に直すべき運用負債です。

特に小規模チームでは「誰が止めるか」が曖昧になりがちです。Claude Codeの設定だけでなく、課金上限を見られる人、DBバックアップを戻せる人、ユーザー向け告知を出せる人を最低1人ずつ決めておくと、事故時の最初の10分が安定します。

関連記事と次の行動

安全設定はClaude CodeセキュリティベストプラクティスとClaude Code権限設定ガイドを先に読むとつながります。コスト事故が気になる場合はClaude Code APIコストガイド、作業証跡を残すなら検証レシートワークフローも合わせて確認してください。

個人で始めるなら、まず無料チートシートで危険コマンドと確認習慣を固定してください。テンプレート化したい場合はClaudeCodeLabの商品一覧へ、チームでCLAUDE.md、権限、hooks、レビュー、障害訓練まで整える場合はClaude Code研修・導入相談が現実的です。

この記事で紹介した内容を実際に試した結果、Masaの検証では、JSON設定、Bash hook、Node.jsラッパーの構文を先に確認してから記事へ入れる流れが一番安定しました。特に「検知より先に封じ込めを書く」「復旧手順と連絡文を同じテンプレートに置く」だけで、Claude Codeへの依頼が曖昧になりにくくなります。小さな本番事故を想定して一度リハーサルすると、自分のリポジトリで足りないアラート、バックアップ、権限設定がかなり見えます。