agent-introspection-debugging

agent-introspection-debugging 技能概覽

agent-introspection-debugging 是用來做什麼的

agent-introspection-debugging 技能是一套結構化的自我除錯流程，專門給卡住、重複迴圈、反覆重試卻沒有進展，或逐漸偏離任務的 AI agent 使用。它不是叫模型「再努力一點」，而是引導 agent 先暫停、捕捉失敗狀態、診斷可能原因、採取一個小範圍的恢復步驟，最後產出一份可讀的除錯報告。

誰適合安裝這個技能

這個技能很適合已經在跑多步驟 AI 工作流程的開發者、agent 建置者與維運人員，尤其是那些會用到工具、檔案或執行環境的情境。它最有價值的地方，通常不是純邏輯錯誤，而是營運層面的失敗：反覆誤用工具、上下文膨脹、環境不相容，或卡在重試迴圈裡。如果你要的是可重複使用的恢復方法，而不是另一個泛用型除錯提示詞，agent-introspection-debugging 會是很好的選擇。

它和一般提示詞有什麼不同

最大的差異在於「收斂」。這個技能會推著 agent 停止盲目重試、記錄發生了什麼，並選擇更小的修正動作，而不是一再燒掉 token。它也設了邊界：它是用來處理 agent 故障恢復，不是用來做完整功能驗證，也不是針對特定框架的精準除錯；若有更窄、更專門的技能，通常會更適合後兩者。

如何使用 agent-introspection-debugging 技能

安裝情境與優先閱讀位置

請依照你平常的技能工作流程，在 affaan-m/everything-claude-code repository 中安裝 agent-introspection-debugging 技能。接著先讀 skills/agent-introspection-debugging/SKILL.md；這個 repo 幾乎完全是透過這個檔案來呈現技能內容，沒有額外的 scripts 或參考資產會把重要行為藏起來。也就是說，你在評估是否採用時，應該把重點放在流程本身，而不是缺少自動化。

什麼時候要呼叫 agent-introspection-debugging

請在某次執行失敗或品質明顯下降之後再使用 agent-introspection-debugging，特別適合以下情況：

• 達到 loop-limit 或 max-tool-call 的失敗
• 反覆重試但始終沒有前進
• prompt drift 或上下文持續成長，導致輸出品質下降
• 檔案系統或環境狀態不一致
• 看起來可透過診斷與更小的下一步來恢復的工具失敗

不要把它當成預設的寫程式流程。它最能發揮作用的時候，是 agent 已經偏離軌道、需要有紀律地把狀態拉回來的時候。

要提供什麼輸入，輸出才會最好

請給這個技能一包精簡的失敗資訊，不要只丟一句「debug this」。比較好的輸入通常會包含：

• 原始目標
• 預期結果
• 實際失敗情況
• 最後一次有意義的 tool-call sequence
• 相關錯誤文字或 stack trace
• 失敗前剛發生了什麼變動
• 目前限制，例如「不要修改超過一個檔案」或「不能連網」

範例提示詞：
“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 模式是：

1. 只有在出現明確失敗模式後才啟用。
2. 在任何新的編輯或重試之前，先強制做捕捉步驟。
3. 要求只做一個有收斂性的恢復動作，不要大改。
4. 在讓 agent 繼續之前，先檢查 introspection report。

實務上，這個技能最強的用法，是拿來縮小下一步行動：確認環境假設、檢查單一可疑檔案，或回復一個有害變更。如果你要求的是「把所有問題都 debug 一遍」，就會失去這個技能最重要的收斂優勢。

agent-introspection-debugging 技能 FAQ

這個技能比一般除錯提示詞更好嗎？

通常是，前提是問題出在 agent 行為，而不只是程式碼缺陷。一般提示詞常會鼓勵更多重試；agent-introspection-debugging skill 更擅長停止迴圈、保留失敗證據，並產出方便人快速檢查的報告。

agent-introspection-debugging 適合新手嗎？

新手也能用，但如果你能辨認 prompt drift、工具迴圈或環境不一致等症狀，效果會更好。若你剛開始接觸，這個技能還是有幫助，因為它提供了像 checklist 一樣的結構；不過如果你能提供具體的失敗證據，而不是泛泛而談，結果會明顯更好。

什麼情況下不該用 agent-introspection-debugging？

如果是例行的程式碼驗證、最終 QA，或有專門技能可用的狹窄框架除錯，就先不要用它。若問題明顯在目前 harness 中無法恢復，例如缺少權限，或 session 內無法修正的基礎設施不可用，也不適合。

repository 裡有自動化嗎，還是只有指引？

就這個技能而言，repository 的證據顯示內容主要在 SKILL.md 的指引，而不是 helper scripts 或 rule files。這不一定是缺點，但代表 agent-introspection-debugging install 不會自動替你強制執行規則。你是在採用一套流程，而這套流程必須由 agent 確實遵守。

如何改進 agent-introspection-debugging 技能

提供更好的證據，不要只寫更長的提示詞

提升輸出品質最大的槓桿，是更精準的失敗捕捉。請包含確切停下來的位置、失敗的 command、最近改了哪些內容，以及目前限制。刪掉無關的歷史資訊。當模型能直接比對「原本要做什麼」和「實際走到哪一步」時，agent-introspection-debugging guide 的效果會更好。

把診斷和恢復分開要求

常見的失敗模式，是把診斷和立即修復混在一起。你可以用更明確的要求來改善 agent-introspection-debugging usage，例如要求它分別輸出：

• 可能的失敗模式
• 信心程度
• 最小的下一步動作
• 完成該動作後的成功檢查

這樣可以避免 agent 從症狀直接跳到一個大而化之、只是猜測的修補方案。

用收斂規則阻止重複破壞

如果前幾次執行已經讓 repo 狀況更糟，請加上限制，例如：

• 編輯前先檢查
• 最多只改一個檔案
• 沒有新的證據前，不要重複執行同一個 command
• 說明為什麼下一步比重試更安全

這些限制和 agent-introspection-debugging for Debugging 的目的非常一致：在保留可恢復性的前提下，減少無效動作。

先迭代第一份報告，不要整個重來

如果第一次 introspection report 品質不好，不要直接換一個全新的提示詞重啟。你可以要求 agent 補齊缺漏部分，例如：「重述可能的根因」、「把證據和假設分開」、「提出更小的恢復動作」。這樣可以保留結構化迴圈，通常也比完全放棄這個技能，更容易得到第二輪的好結果。