Claude-skill-registry incident-handling

目的

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

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

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

<example> <input> 状況: API Gatewayの設定変更後、一部のエンドポイントが502エラーを返す </input> <thinking> 影響範囲を可視化： - 何が壊れたか: /users/* 配下のエンドポイント - 誰に影響するか: モバイルアプリユーザー全員 - どのくらい壊れたか: ユーザー関連機能が完全停止 </thinking> <output> ## 影響範囲

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

</output> </example>

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

<example> <input> 状況: ECSタスクが起動直後にクラッシュを繰り返す </input> <thinking> 問題: ECSタスクがクラッシュ ↓ なぜ？ コンテナがヘルスチェックに失敗 ↓ なぜ？ アプリケーションの起動が遅い ↓ なぜ？ RDSへの初回接続でタイムアウト ↓ 根本原因 セキュリティグループの設定ミスでRDSへの接続が遮断 </thinking> <output> ## 原因分析

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

</output> </example>

3. 復旧戦略の選択

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

<example> <input> 状況: REST API v2への移行後、旧バージョンのクライアントが動作しなくなった </input> <thinking> 復旧戦略の検討： - ロールバック: 可能だが、v2移行済みユーザーに影響 - ホットフィックス: 原因が互換性問題で範囲が広い - 機能フラグ: 該当なし - 互換レイヤー: v1エンドポイントを維持 → 段階的移行可能 </thinking> <output> ## 復旧戦略: 互換レイヤー追加

短期対応

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	リクエスト形式変換

</output> </example>

4. 段階的復旧手順

<example> <input> 状況: RDSのマイグレーション失敗によるサービス停止 </input> <output> ## 復旧手順

Phase 1: 即時対応

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

Phase 2: 復旧作業

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

Phase 3: 検証

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

ロールバック基準

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

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

</example>

5. 複合パターンの検出

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

<example> <input> 状況: 本番環境でLambda関数が断続的にタイムアウトする </input> <thinking> 複合パターンの分析： 1. VPC内Lambda（コールドスタートが遅い） 2. RDS Proxyなし（コネクション枯渇リスク） 3. 同時実行数制限（デフォルト1000）

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

複合パターン検出

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

対応

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

</example>

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

<example> <input> 状況: インシデント復旧完了後 </input> <output> ## ポストモーテム: [インシデント名]

タイムライン

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

根本原因

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

検知の遅延要因

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

復旧の障害要因

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

再発防止策

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

</output> </example>

ADRへの記録

インシデント対応で行った重要な意思決定は

./docs/adr

に記録する。

記録すべき意思決定

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

ADRテンプレート

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

## ステータス
採用

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

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

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

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

適用タイミング

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

アンチパターン

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