Incident Handling

目的

インシデント対応を構造化し、被害最小化・復旧時間短縮・再発防止を実現する。

インシデント対応フレームワーク

1. 初動対応（影響範囲の可視化）

状況: API Gatewayの設定変更後、一部のエンドポイントが502エラーを返す

影響範囲を可視化：

• 何が壊れたか: /users/* 配下のエンドポイント
• 誰に影響するか: モバイルアプリユーザー全員
• どのくらい壊れたか: ユーザー関連機能が完全停止

影響範囲

| 観点 | 状況 | |------|------| | コンポーネント | API Gateway → Lambda統合 | | 影響ユーザー | モバイルアプリユーザー | | 機能喪失度 | ユーザー関連機能が完全停止 | | SEVレベル | SEV1（主要機能停止） |

2. 障害調査（なぜなぜ分析）

状況: ECSタスクが起動直後にクラッシュを繰り返す

問題: ECSタスクがクラッシュ ↓ なぜ？ コンテナがヘルスチェックに失敗 ↓ なぜ？ アプリケーションの起動が遅い ↓ なぜ？ RDSへの初回接続でタイムアウト ↓ 根本原因 セキュリティグループの設定ミスでRDSへの接続が遮断

原因分析

| 層 | 問い | 回答 | |----|------|------| | 表層 | なぜクラッシュ？ | ヘルスチェック失敗 | | 中層 | なぜ失敗？ | 起動が遅い | | 深層 | なぜ遅い？ | RDS接続タイムアウト | | 根本 | SG設定ミス | ECS→RDS間の通信が遮断 |

3. 復旧戦略の選択

| 戦略 | 適用場面 | リスク | |------|----------|--------| | ロールバック | 即時復旧が必要、前バージョンが安定 | データ不整合の可能性 | | ホットフィックス | 問題が明確で修正が小さい | 急いでさらにバグを入れる | | 機能フラグ無効化 | 新機能起因、既存機能は正常 | 一部ユーザーへの影響継続 | | 互換レイヤー追加 | 段階的移行が必要 | 複雑性増加 |

状況: REST API v2への移行後、旧バージョンのクライアントが動作しなくなった

復旧戦略の検討：

• ロールバック: 可能だが、v2移行済みユーザーに影響
• ホットフィックス: 原因が互換性問題で範囲が広い
• 機能フラグ: 該当なし
• 互換レイヤー: v1エンドポイントを維持 → 段階的移行可能

復旧戦略: 互換レイヤー追加

短期対応

1. API Gatewayでv1パスを復活
2. Lambda関数でv1/v2両方のリクエスト形式をサポート

中期対応

1. クライアント側の段階的v2移行
2. v1エンドポイントの廃止スケジュール設定

変更マッピング

| 旧（v1） | 新（v2） | 互換対応 | |----------|----------|----------| | GET /users/{id} | GET /v2/users/{id} | v1パス維持 | | POST /orders | POST /v2/orders | リクエスト形式変換 |

4. 段階的復旧手順

状況: RDSのマイグレーション失敗によるサービス停止

復旧手順

Phase 1: 即時対応

• [ ] CloudWatchアラームの確認
• [ ] 影響を受けるサービスの特定
• [ ] ステータスページ更新
• [ ] スナップショットからの復元可否判断

Phase 2: 復旧作業

• [ ] RDSスナップショットからリストア
• [ ] マイグレーションスクリプトの修正
• [ ] ステージング環境でのテスト

Phase 3: 検証

• [ ] アプリケーションの接続確認
• [ ] E2Eテスト実行
• [ ] CloudWatchメトリクスの正常化確認

ロールバック基準

以下のいずれかに該当する場合、即座にロールバック：

• Phase 2で追加のエラーが発生
• データ整合性の問題が検出される
• 復旧中に新たな障害が発生

5. 複合パターンの検出

単一原因ではなく、複数条件の組み合わせでインシデントが発生することがある。

状況: 本番環境でLambda関数が断続的にタイムアウトする

複合パターンの分析：

1. VPC内Lambda（コールドスタートが遅い）
2. RDS Proxyなし（コネクション枯渇リスク）
3. 同時実行数制限（デフォルト1000）

単独では問題ないが、トラフィック増加時に3つが組み合わさると障害になる。

複合パターン検出

| 条件 | 単独リスク | 複合リスク | |------|-----------|-----------| | VPC内Lambda | 低（コールドスタート遅延） | ↓ | | RDS Proxyなし | 中（コネクション管理） | ↓ | | 同時実行数制限 | 低（通常は十分） | 高（トラフィック増時に障害） |

対応

• RDS Proxyの導入でコネクション管理を改善
• Provisioned Concurrencyでコールドスタート軽減
• 同時実行数の引き上げ申請

6. 事後分析（ポストモーテム）

状況: インシデント復旧完了後

ポストモーテム: [インシデント名]

タイムライン

| 順序 | イベント | |------|----------| | 1 | CloudFormationスタック更新実施 | | 2 | CloudWatchアラーム発報 | | 3 | 原因調査開始 | | 4 | セキュリティグループ設定ミスを特定 | | 5 | 設定修正完了 | | 6 | サービス復旧確認 |

根本原因

CloudFormationテンプレートのセキュリティグループ設定に誤りがあった。

検知の遅延要因

• ECSタスク失敗のアラートが未設定
• RDS接続エラーのログ監視が不十分

復旧の障害要因

• 手動でのSG変更手順が文書化されていなかった
• CloudFormationロールバックが自動化されていなかった

再発防止策

| 対策 | 担当 | 優先度 | |------|------|--------| | CFnテンプレートのレビュープロセス強化 | インフラチーム | 高 | | ECSタスク失敗アラートの追加 | SREチーム | 高 | | ロールバック手順書の作成 | インフラチーム | 中 |

ADRへの記録

インシデント対応で行った重要な意思決定は ./docs/adr に記録する。

記録すべき意思決定

• 復旧戦略の選択理由
• 互換レイヤーの設計判断
• トレードオフを伴った対応

ADRテンプレート

# ADR-XXXX: [インシデント]への対応方針

## ステータス
採用

## コンテキスト
[何が起きたか、影響範囲]

## 決定
[選択した復旧戦略]

## 理由
- [なぜこの戦略を選んだか]
- [他の選択肢を選ばなかった理由]

## 結果
- 残存リスク: [あれば]
- 技術的負債: [発生した場合]

適用タイミング

| タイミング | 適用するフェーズ | |------------|------------------| | 障害検知時 | 1. 初動対応 | | 原因調査中 | 2. 障害調査 | | 対応方針決定時 | 3. 復旧戦略選択 | | 復旧作業中 | 4. 段階的復旧 | | 復旧完了後 | 6. 事後分析 |

アンチパターン

| 振る舞い | 問題 | 代わりに | |----------|------|----------| | 症状だけ治す | 再発する | 根本原因まで掘り下げる | | 影響範囲を確認せず修正 | 二次被害 | 最初に影響範囲を可視化 | | ロールバック手順なしでデプロイ | 復旧が遅れる | 事前にロールバック計画 | | ポストモーテムをスキップ | 同じ失敗を繰り返す | 必ず事後分析を実施 | | 犯人探し | 心理的安全性低下 | システム改善にフォーカス |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HikaruEgashira
• Source: HikaruEgashira/agent-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.