agent-introspection-debugging
作成者 affaan-magent-introspection-debugging スキルは、AI エージェントの失敗に対して構造化された自己デバッグのワークフローを提供します。失敗状態を記録し、原因候補を特定し、範囲を限定した回復ステップを適用し、人間が読める introspection レポートを出力します。ループしやすい実行、再試行が多い処理、挙動がずれやすい処理に向いており、通常の検証用途には適していません。
このスキルは 81/100 点です。エージェントの失敗に対して、明確に発火させやすい自己デバッグのワークフローを備えており、ディレクトリ掲載用として十分に実用的な情報量があります。ループ、挙動のずれ、繰り返し失敗する実行に対して、構造化された回復手順を導入したい利用者には導入価値がありますが、付属ファイルが少ないことと、適用範囲が限定的である点は確認しておくべきです。
- 繰り返し失敗、ループ制限、トークン消費、挙動のずれ、回復可能なツール不具合に対する明確な起動条件がある。
- 失敗の記録、診断、範囲を限定した回復、レポート作成の 4 段階ワークフローが具体的で、エージェントの判断の迷いを減らせる。
- 運用上の位置づけが明快で、これは隠れた実行時機能ではなく、エスカレーション前の自己デバッグ用ワークフローだと明示している。
- スクリプト、参照資料、サポートファイルは含まれていないため、利用者は SKILL.md のワークフローのみに依存する必要がある。
- コード変更後の機能検証や、より狭いフレームワーク固有のデバッグなど、いくつかの用途は明示的に除外されており、適用範囲は広くない。
agent-introspection-debugging スキルの概要
agent-introspection-debugging は何に使うスキルか
agent-introspection-debugging は、失敗している、ループしている、進展なくリトライを繰り返している、あるいはタスクから脱線している AI エージェント向けの、構造化された自己デバッグワークフローです。単にモデルへ「もっと頑張って」と促すのではなく、いったん停止し、失敗時点の状態を記録し、あり得る原因を切り分け、小さな回復アクションを 1 つだけ実行し、読みやすいデバッグレポートを出す流れへ導きます。
このスキルを導入すべき人
このスキルは、ツール、ファイル、実行環境をまたぐ複数ステップの AI ワークフローをすでに運用している開発者、エージェント構築者、運用担当者に向いています。特に効果を発揮するのは、問題が純粋なロジック不備ではなく運用面にあるケースです。たとえば、同じツールの誤用を繰り返す、コンテキストが膨らみすぎる、環境が想定とずれる、リトライループから抜け出せない、といった状況です。汎用的なデバッグ用プロンプトを 1 つ増やすのではなく、再利用できる回復手順がほしいなら、agent-introspection-debugging は有力な選択肢です。
通常のプロンプトと何が違うか
最大の違いは、暴走を抑え込む「封じ込め」にあります。このスキルは、根拠のない再試行を止め、何が起きたかを記録し、トークンを浪費する拡大的な対応ではなく、より小さく限定された修正アクションを選ばせます。同時に適用範囲も明確です。用途はエージェントの失敗からの回復であり、機能全体の検証や、より狭い専用スキルの方が強いフレームワーク固有のデバッグを置き換えるものではありません。
agent-introspection-debugging スキルの使い方
導入時の前提と最初に読むべき場所
affaan-m/everything-claude-code リポジトリで普段使っている skills 導入フローを通じて、agent-introspection-debugging をインストールします。その後、まず skills/agent-introspection-debugging/SKILL.md を読んでください。このリポジトリでは、スキルの実体がほぼそのファイルに集約されており、重要な挙動を左右する追加スクリプトや参照アセットは見当たりません。つまり、導入判断では「自動化が足りないかどうか」ではなく、そのワークフロー自体が自分の運用に合うかを確認するのがポイントです。
agent-introspection-debugging を呼び出すべきタイミング
agent-introspection-debugging は、実行が失敗したあと、または品質が目に見えて劣化したあとに使うのが適しています。特に次のようなケースです。
- loop-limit や max-tool-call に達して失敗した
- リトライを繰り返しているのに前進がない
- prompt drift やコンテキスト肥大化で出力品質が落ちている
- filesystem や環境の状態が想定と食い違っている
- ツール実行に失敗しているが、診断して次の一手を狭めれば回復できそう
通常のコーディングフローのデフォルトとして常時使うものではありません。エージェントが明らかに脱線したあと、規律ある回復が必要な場面でこそ価値が出ます。
どんな入力だと良い出力になりやすいか
このスキルに渡すべきなのは、「debug this」のような曖昧な依頼ではなく、要点を絞った failure packet です。良い入力には通常、次が含まれます。
- 元のゴール
- 期待していた結果
- 実際の失敗内容
- 最後に意味のあった tool-call の並び
- 関連するエラーテキストや stack trace
- 失敗直前に変わったこと
- 「1 ファイル以上は編集しない」「ネットワークアクセス禁止」のような現在の制約
例のプロンプト:
“Use agent-introspection-debugging for Debugging. Goal: update auth middleware tests. Expected: green test run. Actual: agent retried npm test 6 times, then edited unrelated files. Error: MODULE_NOT_FOUND in tests/auth.spec.ts. Last useful actions: edited jest.config.js, ran tests, listed files. Constraints: no dependency upgrades, keep changes minimal. Produce failure capture, diagnosis, one contained recovery action, and a short introspection report.”
この形が有効なのは、ノイズに引っ張られず、根本原因と周辺症状を切り分けるのに十分な証拠をスキルへ渡せるからです。
実践的な運用フローと期待できる出力
良い agent-introspection-debugging usage パターンは、次の流れです。
- 明確な失敗パターンが現れてから起動する
- 新しい編集やリトライの前に、必ず failure capture をさせる
- 広範囲な書き換えではなく、限定された回復アクションを 1 つだけ求める
- エージェントを再開させる前に、introspection report を確認する
実運用では、このスキルは「次の一手を狭める」ときに最も力を発揮します。たとえば、環境前提を確認する、疑わしいファイルを 1 つだけ調べる、悪影響のある変更を 1 つだけ戻す、といった使い方です。「全部まとめてデバッグして」と依頼すると、このスキルの価値である封じ込め効果が薄れてしまいます。
agent-introspection-debugging スキル FAQ
普通のデバッグ用プロンプトより優れていますか？
多くの場合は yes です。特に、問題の中心がコード欠陥そのものではなく、エージェントの振る舞いにあるときに向いています。通常のプロンプトは、かえってリトライを増やしがちです。agent-introspection-debugging skill は、ループを止め、失敗時の証拠を保全し、人間が短時間で確認できるレポートを出させる点で優れています。
agent-introspection-debugging は初心者にも向いていますか？
初心者でも使えますが、prompt drift、ツールループ、environment mismatch といった症状をある程度見分けられると、より効果的です。まだ不慣れでも、このスキルにはチェックリスト的な構造があるため助けになります。ただし、漠然とした説明だけを渡すより、具体的な失敗の証拠を添えたほうが結果は明らかに良くなります。
agent-introspection-debugging を使わないほうがよい場面は？
定常的なコード検証、最終 QA、あるいは専用スキルが存在する狭いフレームワークデバッグには使わないほうがよいです。また、現在の harness 内では明らかに回復不能な問題、たとえば不足している権限や、セッション内からはどうにもできないインフラ停止のようなケースでも適しません。
リポジトリには自動化がありますか、それともガイダンス中心ですか？
このスキルについては、リポジトリ上の根拠は SKILL.md にあるガイダンスが中心で、helper script や rule file は見当たりません。これは必ずしも弱点ではありませんが、agent-introspection-debugging install だけで自動的に強制される仕組みは得られない、という意味ではあります。導入するのは「ツール」そのものというより、エージェントがきちんと守るべきワークフローです。
agent-introspection-debugging スキルを改善するには
長いプロンプトより、良い証拠を渡す
出力品質に最も効くのは、失敗の捉え方を鋭くすることです。正確な停止地点、失敗したコマンド、直前の編集、そして制約を含めてください。関係のない履歴は省きます。モデルがノイズを読み込まずに、意図した行動と実際の軌跡を比較できるほど、agent-introspection-debugging guide の質は上がります。
診断と回復を分けて依頼する
よくある失敗は、診断を飛ばして即座の修復に潰してしまうことです。agent-introspection-debugging usage を改善するには、次を明示的に要求してください。
- あり得る失敗パターン
- 確信度
- 最小の次アクション
- そのアクション後の成功確認方法
こうしておくと、症状から大きな推測修正へ飛びつくのを防げます。
封じ込めルールで再被害を防ぐ
過去の実行でリポジトリの状態が悪化したなら、次のような制限を追加してください。
- 編集前にまず調査する
- 変更は最大 1 ファイル
- 新しい証拠なしに同じコマンドを繰り返さない
- 次のアクションが、単なるリトライより安全な理由を要約する
これらの制約は、agent-introspection-debugging for Debugging の狙いと強く一致しています。つまり、回復可能性を保ちながら、無駄なアクションを減らすことです。
最初のレポートを改善し、最初からやり直さない
最初の introspection report が弱くても、まったく新しいプロンプトでやり直さないでください。足りない部分だけを絞って改善させます。たとえば、「root cause candidates を言い直して」「evidence と assumptions を分けて」「より小さい recovery action を提案して」といった依頼です。このほうが構造化されたループを維持でき、スキル自体を放棄するより、2 回目で良い結果が出やすくなります。