エージェント内省デバッグ は何をしますか？
このスキルは、エージェント実行が繰り返し失敗する場合、トークンを消費しながら進捗しない場合、同じツールをループする場合、または意図したタスクから逸脱している場合に使用します。
これはワークフロースキルであり、隠れたランタイムではありません。エージェントが人間にエスカレーションする前に、体系的に自己デバッグすることを教えます。
アクティブ化のタイミング
- 最大ツールコール数 / ループ制限に達した場合
- 前に進まずに同一の再試行を繰り返す場合
- コンテキストの肥大化やプロンプトのドリフトが出力品質を低下させ始めた場合
- 想定と現実のファイルシステム / 環境状態が一致しない場合
- 診断と小さな是正措置で回復可能と思われるツール障害が発生した場合
スコープの境界
このスキルは以下のためにアクティブ化します：
- 盲目的な再試行の前に障害状態をキャプチャするため
- 一般的なエージェント固有の障害パターンを診断するため
- 限定された復旧アクションを適用するため
- 構造化された人間可読なデバッグレポートを生成するため
以下のために主要な情報源としてこのスキルを使用しないでください：
- コード変更後の機能検証（
verification-loopを使用してください） - より狭いECCスキルが既に存在する場合のフレームワーク固有のデバッグ
- 現在のハーネスが自動的に強制できないランタイムの保証
4フェーズのループ
フェーズ1: 障害キャプチャ
回復を試みる前に、障害を正確に記録します。
キャプチャする内容：
- エラータイプ、メッセージ、スタックトレース（利用可能な場合）
- 最後の意味のあるツールコールシーケンス
- エージェントが何をしようとしていたか
- 現在のコンテキスト圧力：繰り返されるプロンプト、過度に大きなペーストログ、重複した計画、暴走するメモ
- 現在の環境の前提：カレントディレクトリ、ブランチ、関連するサービス状態、想定されるファイル
最小限のキャプチャテンプレート：
## 障害キャプチャ
- セッション / タスク：
- 進行中の目標：
- エラー：
- 最後の成功したステップ：
- 最後に失敗したツール/コマンド：
- 確認された繰り返しパターン：
- 検証すべき環境の前提：
フェーズ2: ルート原因診断
何かを変更する前に、障害を既知のパターンに照合します。
| パターン | 考えられる原因 | チェック内容 |
|---|---|---|
| 最大ツールコール数 / 同じコマンドの繰り返し | ループまたは終了しないオブザーバーパス | 直近N回のツールコールを繰り返しについて検査する |
| コンテキストオーバーフロー / 推論能力低下 | 無制限のメモ、繰り返される計画、過度に大きなログ | 最近のコンテキストを重複と低シグナルの塊について検査する |
ECONNREFUSED / タイムアウト | サービス利用不可またはポート間違い | サービス状態、URL、ポートの前提を確認する |
429 / クォータ枯渇 | 再試行ストームまたはバックオフ不足 | 繰り返し呼び出しをカウントし、再試行間隔を検査する |
| 書き込み後にファイルが存在しない / 差分が古い | 競合、間違ったCWD、またはブランチのドリフト | パス、CWD、gitステータス、実際のファイル存在を再確認する |
| 「修正」後もテストが失敗する | 間違った仮説 | 正確に失敗しているテストを特定し、バグを再導出する |
診断の質問：
- これはロジック障害、状態障害、環境障害、それともポリシー障害ですか？
- エージェントは本来の目的を見失い、間違ったサブタスクの最適化を始めていませんか？
- 障害は決定論的ですか、それとも一時的ですか？
- 診断を検証するための最小の可逆アクションは何ですか？
フェーズ3: 限定復旧
診断対象を変更する最小のアクションで復旧します。
安全な復旧アクション：
- 繰り返しの再試行を停止し、仮説を言い直す
- 低シグナルのコンテキストをトリミングし、アクティブな目標、ブロッカー、証拠のみを保持する
- 実際のファイルシステム / ブランチ / プロセス状態を再確認する
- タスクを1つの失敗コマンド、1ファイル、または1テストに絞り込む
- 推測的な推論から直接観察に切り替える
- 障害が高リスクまたは外部ブロックされている場合は人間にエスカレーションする
実際に現在の環境で実際のツールを使用して行っていない限り、「エージェント状態をリセットする」や「ハーネス設定を更新する」などのサポートされていない自動修復アクションを主張しないでください。
限定復旧チェックリスト：
## 復旧アクション
- 選択した診断：
- 取った最小アクション：
- これが安全である理由：
- 修正が成功したことを証明する証拠：
フェーズ4: 内省レポート
次のエージェントまたは人間が回復プロセスを理解できるようにするレポートで終了します。
## エージェント自己デバッグレポート
- セッション / タスク：
- 障害：
- 根本原因：
- 復旧アクション：
- 結果：成功 | 部分的成功 | ブロック
- トークン / 時間消費リスク：
- 必要なフォローアップ：
- 後でエンコードする予防的変更：
復旧ヒューリスティック
以下の介入を順に優先します：
- 本当の目的を一文で言い直す。
- メモリを信頼するのではなく、世界の状態を確認する。
- 失敗スコープを縮小する。
- 1つの識別チェックを実行する。
- その後にのみ再試行する。
悪いパターン：
- 同じアクションをわずかに異なる文言で3回再試行する
良いパターン：
- 障害をキャプチャする
- パターンを分類する
- 1つの直接チェックを実行する
- チェックがサポートする場合のみ計画を変更する
ECCとの統合
- コードが変更された場合、復旧後に
verification-loopを使用する。 - 障害パターンを見直しや将来のスキルにする価値がある場合は
continuous-learning-v2を使用する。 - 問題が技術的障害ではなく決定の曖昧さである場合は
councilを使用する。 - 障害がローカル状態の競合やリポジトリのドリフトに起因する場合は
workspace-surface-auditを使用する。
出力基準
このスキルがアクティブな場合、「修正しました」だけで終了しないでください。
常に以下を提供してください：
- 障害パターン
- ルート原因の仮説
- 復旧アクション
- 状況が改善されたか、または依然としてブロックされていることを示す証拠