agent-introspection-debugging

agent-introspection-debugging 技能概览

agent-introspection-debugging 适合解决什么问题

agent-introspection-debugging 是一套面向 AI agent 的结构化自我调试工作流，适用于 agent 出现失败、循环重试、反复尝试却没有进展，或逐渐偏离任务目标的场景。它不是简单让模型“再努力一点”，而是引导 agent 先暂停、记录当前失败状态、判断最可能的原因、执行一个小范围的恢复动作，并输出一份可读的调试报告。

谁适合安装这个技能

这个技能适合已经在运行多步骤 AI 工作流的开发者、agent 构建者和运维人员，尤其是那些流程里会涉及工具、文件或执行环境的人群。它在“操作层面”的失败场景中最有价值，而不只是纯逻辑错误，比如：反复错误使用工具、上下文膨胀、环境不一致，或者卡在无效重试循环里。如果你想要的是一种可复用的恢复方法，而不是再加一个泛泛的调试提示词，那么 agent-introspection-debugging 会很适合。

它和普通调试提示词有什么不同

agent-introspection-debugging 最大的区别在于“收敛与约束”。它会推动 agent 停止盲目重试，先把发生了什么记录清楚，再选择一个更小、更可控的纠偏动作，而不是继续消耗 token 不断升级问题。它的边界也很明确：这是一个用于 agent 故障恢复的技能，不是完整功能验证工具，也不是特定框架的深度调试方案；在后两类场景里，更垂直的技能通常会更有效。

如何使用 agent-introspection-debugging 技能

安装背景与优先阅读位置

通过你平常的 skills 工作流，为 affaan-m/everything-claude-code 仓库安装 agent-introspection-debugging 技能。安装后，优先阅读 skills/agent-introspection-debugging/SKILL.md；这个仓库里，这个技能几乎完全通过这个文件来呈现，没有额外脚本或参考资源把关键行为藏在别处。这也意味着，你在决定是否采用 agent-introspection-debugging 时，重点应该放在它的工作流设计本身，而不是期待额外自动化能力。

什么时候调用 agent-introspection-debugging

建议在一次运行已经明显失败或质量下降之后再使用 agent-introspection-debugging，尤其适合下面这些情况：

• 触发 loop-limit 或 max-tool-call 失败
• 多次重试但没有任何实质进展
• prompt 漂移或上下文不断变长，导致输出质量下滑
• 文件系统状态或运行环境状态不一致
• 工具调用失败，但看起来可以先诊断，再通过更小的下一步恢复

不要把它当成默认编码流程来用。agent-introspection-debugging 的价值，主要体现在 agent 已经“脱轨”且需要一种有纪律的恢复方式时。

什么样的输入最容易产出高质量结果

给这个技能输入一个紧凑的“失败信息包”，而不是只说一句“debug this”。高质量输入通常包括：

• 原始目标
• 预期结果
• 实际失败表现
• 最后一次有意义的 tool-call 序列
• 相关错误文本或 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。

在实际使用中，agent-introspection-debugging 最强的地方，是帮助你把“下一步”收窄：确认环境假设、检查一个可疑文件，或者撤销一次有害改动。如果你直接要求它“把所有问题都 debug 掉”，反而会失去这个技能最有价值的收敛优势。

agent-introspection-debugging 技能常见问题

这个技能比普通调试提示词更好吗？

大多数情况下是的，前提是问题出在 agent 行为本身，而不只是代码缺陷。普通提示词往往会让模型继续重试；而 agent-introspection-debugging skill 更擅长及时叫停循环、保留失败证据，并生成一份人类可以快速审阅的报告。

agent-introspection-debugging 适合新手吗？

可以用，但它更适合那些能够识别 prompt 漂移、工具循环、环境不一致这类症状的人。如果你是刚入门，agent-introspection-debugging 依然有帮助，因为它会强制引入一种类似 checklist 的结构；不过，如果你能提供具体的失败证据，而不是宽泛描述，效果会明显更好。

什么情况下不该使用 agent-introspection-debugging？

如果只是做日常代码验证、最终 QA，或者正在处理某个框架下非常具体的调试问题，而且已经有更专业的技能可用，那就不建议用 agent-introspection-debugging。另外，如果问题在当前运行环境里显然无法恢复，比如权限缺失，或基础设施不可用且 agent 无法在当前会话内修复，也应该跳过它。

仓库里包含自动化能力，还是只有操作指引？

从仓库现有内容来看，这个技能的核心证据在 SKILL.md，而不是辅助脚本或规则文件。这个事实不一定是缺点，但它意味着 agent-introspection-debugging install 并不会自动替你执行约束或检查。你真正采用的是一套需要 agent 自觉遵守的工作流。

如何改进 agent-introspection-debugging 技能使用效果

提供更好的证据，而不是更长的提示词

影响输出质量最大的杠杆，是把失败记录得更准确。尽量提供明确的停止点、失败命令、最近的修改以及当前约束；无关历史则尽量省略。agent-introspection-debugging guide 的效果，会在模型能够直接对比“本来想做什么”和“实际走向了哪里”时明显提升，而不是被噪声拖慢。

将诊断与恢复动作拆开请求

一个常见失败模式，是把诊断和立即修复混在一起。要提升 agent-introspection-debugging usage 的效果，最好明确要求输出：

• 最可能的失败模式
• 置信度
• 最小下一步动作
• 执行该动作后的成功检查方式

这样可以避免 agent 从表面症状直接跳到大而不稳的猜测性修复。

用收敛规则阻止重复性破坏

如果之前的运行已经把仓库改得更糟，可以加入这些限制：

• 先检查，再编辑
• 最多只改一个文件
• 没有新证据时，不重复执行同一命令
• 说明为什么下一步比继续重试更安全

这些约束与 agent-introspection-debugging for Debugging 的目标高度一致：在保留可恢复性的前提下，减少无效动作和重复伤害。

基于第一版报告迭代，而不是从头重来

如果第一版 introspection report 质量不高，不要直接用一条全新的提示词从头开始。更好的做法是让 agent 补齐缺失部分，比如：“重新陈述根因候选项”、“把证据和假设分开”、“提出一个更小的恢复动作”。这样能保留原有的结构化循环，通常也比彻底放弃这个技能、更容易在第二轮拿到更好的结果。