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