| name | error-recovery |
| description | レジリエントなエージェントワークフローのためのエラーハンドリング、チェックポイント管理、リカバリパターン。
Anthropic のロングランニングエージェントガイダンスとグレースフルデグラデーションに基づく。
以下の場合に使用:
- 失敗する可能性のある複雑なワークフローの実装
- チェックポイント/再開機能が必要な場合
- ツール障害のグレースフルハンドリング
- エージェントエラーとリトライの管理
- 堅牢な自動化の構築
Trigger phrases: error handling, recovery, checkpoint, resume, graceful degradation, retry, fallback
|
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash, TodoWrite |
| model | sonnet |
| user-invocable | true |
エラーリカバリパターン
エラーをグレースフルに処理し、進捗をチェックポイントし、障害からのリカバリを可能にするレジリエントなエージェントワークフロー構築のための戦略。
Building Effective Agents より:
「エージェントは各ステップで環境からグラウンドトゥルースを取得し（ツール呼び出し結果やコード実行など）、進捗を評価すべきである。」
「エージェントはチェックポイントで一時停止してフィードバックを求めたり、ブロッカーに遭遇した場合に停止できる。」
基本原則
1. 早期失敗、迅速回復
エラーを早期に検出し、頻繁にチェックポイントし、最後に正常だった状態から再開する。
2. グラウンドトゥルース検証
次に進む前に、各アクションの結果を必ず検証する。
3. グレースフルデグラデーション
理想的なパスが失敗した場合、完全な失敗ではなく代替アプローチにフォールバックする。
チェックポイントシステム
チェックポイントのタイミング
| イベント | チェックポイントアクション |
|---|
| 機能完了 | feature-list.json を更新、コミット |
| 重要なファイル変更 | 進捗ログを更新 |
| リスクのある操作の前 | 現在の状態を記録 |
| テスト成功後 | パス状態を記録 |
| 外部 API 呼び出し前 | リクエストコンテキストを保存 |
チェックポイント形式
{
"checkpointId": "CP-001",
"timestamp": "2025-01-16T14:30:00Z",
"position": {
"phase": "Implementation",
"feature": "F003",
"step": "Writing AuthService"
},
"state": {
"filesModified": ["src/services/auth.ts"],
"testsStatus": "passing",
"lastSuccessfulAction": "Created AuthService class"
},
"recovery": {
"nextAction": "Add login method to AuthService",
"dependencies": ["User model exists", "Database connected"
チェックポイントの実装
## 各重要アクション後に:
1. **成功を検証**
- ツール出力にエラーがないか確認
- 簡易バリデーションを実行（lint、型チェック）
- ファイルが正しく書き込まれたことを確認
2. **状態を記録**
- .claude/workspaces/{workspace-id}/claude-progress.json を更新
- 進捗ログにエントリを追加
- 変更されたファイルを記録
3. **リカバリパスを記録**
- 次のステップが失敗した場合の対処
- 必要に応じたロールバック方法
- 再開に必要な依存関係
エラーカテゴリと対応
カテゴリ 1: 一時的エラー
リトライで成功する可能性がある一時的な障害。
| エラータイプ | 例 | 対応 |
|---|
| ネットワークタイムアウト | API 呼び出し失敗 | 指数バックオフでリトライ |
| レート制限 | リクエスト過多 | 待機してリトライ |
| 一時的なファイルロック | ファイル使用中 | 短時間待機、リトライ |
指数バックオフ + ジッターによるリトライ戦略:
max_retries = 3
base_delay = 1s
for attempt in 1..max_retries:
result = try_operation()
if success:
return result
# 指数バックオフ + ジッターでサンダリングハード問題を防止
jitter = random(0, 0.5 * base_delay)
wait(base_delay * 2^attempt + jitter)
escalate_to_user("Operation failed after 3 retries")
ジッターが重要な理由: ジッターがないと、同時にリトライする複数のエージェントが同じ間隔でシステムを圧迫する可能性がある（サンダリングハード問題）。ランダム性を加えることでリトライの試行を分散できる。
カテゴリ 2: 回復可能なエラー
異なるアプローチが必要だが、処理可能なエラー。
| エラータイプ | 例 | 対応 |
|---|
| ファイル未発見 | 期待されるファイルがない | 代替を検索 |
| 権限拒否 | ディレクトリに書き込めない | ユーザーに権限を要求 |
| 依存関係不足 | パッケージ未インストール | インストールまたは代替を使用 |
| テスト失敗 | 新コードがテストを破壊 | 障害を分析、コードを修正 |
リカバリ戦略:
1. 完全なコンテキストでエラーをログ記録
2. 根本原因を分析
3. 代替アプローチを決定
4. 代替が存在する場合:
- 元の計画からの逸脱を記録
- 代替を実行
- 成功を検証
5. 代替がない場合:
- ブロッカーを記録
- ユーザーにガイダンスを求める
カテゴリ 3: 致命的エラー
人間の介入が必要なエラー。
| エラータイプ | 例 | 対応 |
|---|
| 認証が必要 | API キー不足 | ユーザーに提供を依頼 |
| データ破損 | 無効な状態 | 停止してユーザーに通知 |
| セキュリティ懸念 | 不審な操作 | 停止して報告 |
| スコープの逸脱 | リクエストが境界を超えている | ユーザーと確認 |
致命的エラープロトコル:
1. 全操作を即座に停止
2. 現在の状態をチェックポイント
3. 完全なコンテキストでエラーを記録:
- 何を試みたか
- 何が失敗したか
- ファイルの現在の状態
- 潜在的な影響
4. ユーザーに明確な選択肢を提示:
- 修正して続行
- ロールバックしてリトライ
- ワークフローを中止
グレースフルデグラデーションパターン
パターン 1: フォールバックチェイン
主要なアプローチを試み、代替にフォールバック。
主要: 推奨ライブラリを使用
│
└─ (失敗) ─▶ フォールバック 1: 代替ライブラリを使用
│
└─ (失敗) ─▶ フォールバック 2: 手動実装
│
└─ (失敗) ─▶ ユーザーに問い合わせ
パターン 2: 部分的成功
可能なものを完了し、できなかったものを報告。
## 部分的成功レポート
### 完了（5 機能中 3 機能）
- [x] ユーザー登録
- [x] ユーザーログイン
- [x] パスワードリセット
### 失敗（5 機能中 2 機能）
- [ ] OAuth 統合 - エラー: client_id が不足
- [ ] 2FA - エラー: SMS プロバイダー未設定
### 次のステップ
1. .env に OAuth client_id を提供
2. 設定で SMS プロバイダーを構成
3. 残りの機能に対して /spec-plan を再実行
パターン 3: セーフモード
エラー発生時に機能を縮小して続行。
通常モード:
- 全機能の完全実装
- 完全なテストカバレッジ
- パフォーマンス最適化
セーフモード（エラー時）:
- コア機能のみ
- 基本テスト
- 最適化をスキップ
- スキップした内容を後で対応するよう記録
パターン 4: サーキットブレイカー
障害が発生しているサービスへのリクエストを停止し、連鎖障害を防止。
AI Agent Best Practices より:
「リトライとフォールバックは障害からの回復を試みる。サーキットブレイカーは悪い状況がさらに悪化するのを防ぐ。」
状態:
CLOSED（通常） ──[failures >= threshold]──▶ OPEN（ブロック中）
▲ │
│ [timeout expires]
│ ▼
└────────[success]────────── HALF-OPEN（テスト中）
│
[failure]
▼
OPEN（ブロック中）
実装:
circuit_breaker:
failure_threshold: 3 # OPEN にするための連続失敗数
timeout: 30s # 再テストまでの待機時間
state: CLOSED
on_operation():
if state == OPEN:
if timeout_expired:
state = HALF_OPEN
else:
return "Service unavailable (circuit open)"
result = try_operation()
if success:
if state == HALF_OPEN:
state = CLOSED
failure_count = 0
return result
else:
failure_count++
if failure_count >= failure_threshold:
state = OPEN
start_timeout()
return error
使用場面:
| シナリオ | サーキットブレイカーを使用 |
|---|
| 外部 API 呼び出し | はい - 障害中の API への過負荷を防止 |
| データベース操作 | はい - コネクション枯渇を防止 |
| ファイルシステム操作 | 場合による - 障害モードに依存 |
| インメモリ操作 | いいえ - 障害は即座に発生 |
エージェント固有の考慮事項:
複数の AI エージェントをチェインする場合:
- 各エージェントの信頼性が 95% なら、3 エージェントで全体は 86%
- 各段階のサーキットブレイカーで連鎖障害を防止
- 完全な失敗ではなく、可能な場合は部分的な結果を使用
サブエージェントのサーキットブレイカー閾値
自律エージェントループの実績ある閾値（Claude Code エンジニアリングベストプラクティスより）:
| 閾値 | 値 | アクション |
|---|
| NO_PROGRESS | 3 ループ | ファイル変更なしで 3 ループ後に停止 |
| SAME_ERROR | 5 回 | 同一エラー 5 回でエスカレーション |
| OUTPUT_DECLINE | 70% | 出力品質が 70% 以上低下したら一時停止 |
適用: 各サブエージェント呼び出しで files_changed、error_messages、output_quality を追跡する。閾値に達したらリトライを停止し、状況と選択肢についてユーザーに明確に伝える。
リカバリワークフロー
ワークフロー 1: クラッシュ後の再開
1. 現在のワークスペース ID を特定（ブランチ + パスハッシュ）
2. .claude/workspaces/{workspace-id}/claude-progress.json を読む
3. 最後のチェックポイントを特定:
- 位置: "Phase 5, Feature F003, step 2"
- 最後のアクション: "Created AuthService class"
- 次のアクション: "Add login method"
4. ファイル状態を検証:
- `git status` でコミットされていない変更を確認
- ファイルをチェックポイントの期待値と比較
5. 状態が有効な場合:
- 記録された次のアクションから続行
6. 状態が破損している場合:
- 最後のコミットにロールバック: `git checkout -- .`
- そのチェックポイントから再開
ワークフロー 2: テスト失敗のリカバリ
1. 実装後にテストが失敗
2. 障害を分析:
- エラーメッセージを読む
- 失敗しているアサーションを特定
- コード変更まで追跡
3. 修正を決定:
- 新コードのバグの場合: 修正して再実行
- テストのバグの場合: テストの期待値をレビュー
- 設計問題の場合: アーキテクトに相談
4. 修正を適用
5. 全テストスイートを実行
6. 全テスト合格時のみチェックポイントを更新
ワークフロー 3: マージコンフリクトのリカバリ
1. pull/merge 中にコンフリクトを検出
2. 現在のブランチ状態をチェックポイント
3. コンフリクトを分析:
- 競合ファイルを一覧
- 両バージョンを理解
4. コンフリクトを解決:
- 各ファイルで正しいバージョンを決定
- ローカルで解決をテスト
5. 解決をコミット
6. ワークフローを続行
進捗トラッキングとの統合
進捗ファイルのエラーログ
{
"log": [
{
"timestamp": "2025-01-16T14:30:00Z",
"action": "Attempted OAuth integration",
"status": "failed",
"error": {
"type": "ConfigurationError",
"message": "Missing OAUTH_CLIENT_ID in environment",
"recoverable": true,
"resolution": "User must provide OAuth credentials"
}
}
],
"blockers": [
{
"id": "B001",
"description": "OAuth credentials required",
"status": "waiting_for_user"
ブロッカー管理
## ブロッカープロトコル
1. **検出**: 進捗がブロックされていることを特定
2. **記録**: 進捗ファイルのブロッカー配列に追加
3. **通知**: 明確な説明でユーザーに通知
4. **待機**: ブロッカーを超えて進まない
5. **解決**: ユーザーが解決策を提供したら:
- ブロッカーを解決済みとしてマーク
- 解決アクションをログ記録
- ワークフローを続行
## ブロッカー状態
| 状態 | 意味 |
|------|------|
| waiting_for_user | ユーザーの入力/アクションが必要 |
| investigating | 潜在的な解決策を分析中 |
| resolved | ブロッカー解消 |
| escalated | 外部の支援が必要 |
Claude Code 固有の機能
チェックポイントの使用
Claude Code は各編集前に自動的にチェックポイントを作成する。
- 安全な実験: 恐れずにアプローチを試せる
/rewind を使用: 必要に応じて以前の状態にロールバック- Esc を 2 回押す: 現在の操作をキャンセルして相談
リカバリコマンド
| コマンド | 使用場面 |
|---|
/rewind | 最近の変更を元に戻す必要がある時 |
/clear | コンテキストが汚染されすぎた場合、クリーンに再開 |
git checkout -- file | 特定ファイルの変更を破棄 |
git stash | 作業中の内容を一時保存 |
アンチパターン
| アンチパターン | 悪い理由 | 代わりに |
|---|
| エラーを無視 | 問題が複合化 | 即座に対処 |
| チェックポイントなし | リカバリできない | 頻繁にチェックポイント |
| バックオフなしのリトライ | 問題を悪化させる可能性 | 指数バックオフを使用 |
| サイレント障害 | 問題が隠れる | 常にログと報告 |
| ブロッカーを超えて続行 | 無効な状態になる | 停止して解決 |
Rules (L1 - Hard)
信頼性のあるリカバリとデータ安全性に不可欠。
- ALWAYS: リスクのある操作の前にチェックポイント（ロールバックを可能にする）
- ALWAYS: 各重要アクション後に成功を検証（グラウンドトゥルース）
- NEVER: エラーメッセージや警告を無視しない（問題が複合化）
- NEVER: ユーザーの確認なしにブロッカーを超えて続行しない
- NEVER: 作業を失わない - 早期に頻繁にコミット
- ALWAYS: 自律エージェントループにサーキットブレイカー閾値を適用:
- NO_PROGRESS: ファイル変更なしで 3 ループ後に停止
- SAME_ERROR: 同一エラー 5 回でユーザーにエスカレーション
- OUTPUT_DECLINE: 出力品質が 70% 以上低下したら一時停止
- MUST: サーキットブレイカー閾値に達したらユーザーにエスカレーション
Defaults (L2 - Soft)
運用品質に重要。適切な理由がある場合はオーバーライド可。
- 完全なコンテキストでエラーを記録する（デバッグを支援）
- エラー報告時にリカバリオプションを提供する
- リトライには指数バックオフを使用する
- タイムスタンプ付きで全失敗試行をログ記録する
Guidelines (L3)
堅牢なエラーハンドリングのための推奨事項。
- consider: 開発中にリカバリパスのテストを検討
- prefer: 完全な失敗よりグレースフルデグラデーションを推奨
- consider: 迅速なロールバックに Claude Code の
/rewind の使用を検討
