Agent Introspection Debugging Skill：让 AI Agent 学会自我诊断

AI Agent 跑崩了、原地打转、Token 烧光也没进展——这是让所有 AI 编程用户头疼的问题。Agent Introspection Debugging 是一个结构化自我诊断 Skill，教会 Agent 在失败时先「捕捉证据」再行动，而不是盲目重试白白消耗 Token。它是 AI Coding Agent 走向生产可用的关键一步：在失控前把根因定位清楚。

功能与原则

核心能力是将 Agent 级别的调试流程标准化：Capture（记录失败状态）→ Diagnose（匹配已知失败模式）→ Recover（最小化修正）→ Report（生成结构化报告）。设计原则是「诊断先于修复」——盲目重试是对 Token 的最大浪费，而精确诊断往往只需要一条最小化修正就能恢复。

认可度

来自 affaan-m/ECC（The agent harness performance optimization system）仓库，截至 2026-08-15，ECC 在 SkillsMP 平台记录下载量约 239.9k，其下多个 Skill 近期频繁更新。该 Skill 本身于 2026-08-12 刚刚更新，反映出作者对 Agent 可靠性问题的持续投入。HN、Reddit r/ClaudeAI 上关于「Agent 调试」和「Token 浪费」的讨论在 2026 年下半年明显增多，带火了一批类似工作流类 Skill。

链接

GitHub：https://github.com/affaan-m/ECC

原作者

affaan-m（GitHub username: affaan-m），ECC 项目维护者。ECC 是一个面向 Claude Code、Codex、Cursor、Opencode 等主流 AI 编程工具的 Agent 性能优化系统，涵盖 Skills、记忆、安全和工作流等多个维度，在多平台开发者群体中有较高影响力。

介绍

ECC 的 Agent Introspection Debugging Skill 解决的是一个非常具体但普遍的问题：当 Agent 运行失败时，它不会「思考自己为什么失败」，而是根据错误信息直接重试，导致同样的错误重复出现，甚至陷入无限循环。这个 Skill 为 Agent 提供了一套标准化的自我调试流程。

它的工作方式分为四个阶段。首先是 Capture（捕捉）：精确记录错误类型、消息、栈追踪（如果有）、最后一次有意义的工具调用序列、Agent 当时正在尝试完成的任务、当前上下文压力（重复 prompt、过大的日志、低信号内容），以及当前环境假设（工作目录、分支、相关服务状态、期望存在的文件）。捕获模板是结构化的，确保不遗漏关键信息。

其次是 Diagnose（诊断）：将捕捉到的失败匹配到已知失败模式表中。例如「最大工具调用次数 / 重复相同命令」对应「循环或无退出路径」，「上下文溢出 / 推理降级」对应「无界笔记、重复计划、超大日志」，「ECONNREFUSED / 超时」对应「服务不可用或端口错误」，「429 / 配额耗尽」对应「重试风暴或缺少退避」，「文件写入后缺失 / diff 陈旧」对应「竞态、错误 cwd 或分支漂移」。诊断完成后，Agent 需要回答四个问题：这是逻辑失败、状态失败、环境失败还是策略失败？Agent 是否丢失了真实目标开始优化错误的子任务？失败是确定性的还是临时性的？什么是最小的可逆操作可以验证诊断？

然后是 Recover（恢复）：基于诊断结果执行最小化修正动作，而非全面重写。安全恢复动作包括停止重复重试并重新陈述假设、裁剪低信号内容并重新开始、验证服务健康状态、检查路径和 git 状态、隔离具体失败测试并重新推导 bug 等。

最后是 Report（报告）：生成一份结构化的人类可读调试报告，包含失败捕获、匹配模式、诊断结论、执行的恢复动作，以及验证结果。这份报告可以让人类快速介入，或为下一次同类问题提供参考。

特点

• 结构化四阶段流程：Capture → Diagnose → Recover → Report，避免盲目重试
• 失败模式匹配表：内置常见 Agent 失败原因（循环、上下文膨胀、超时、配额耗尽、文件状态不一致）的快速诊断路径
• 最小化修正原则：只做「能改变诊断面的最小动作」，而非全面重写
• 环境假设验证：显式检查 cwd、git status、文件实际存在性，防止 Agent 基于错误假设行动
• 兼容多 Agent 平台：适用于 Claude Code、Codex、Cursor、Opencode 等主流 AI 编程工具
• 记录-修复闭环：每次失败都有记录，防止同一错误重复踩坑

使用方法

在支持 Skills 的 AI 编程工具中安装该 Skill，安装命令为：

npx skills add https://github.com/affaan-m/ECC --skill agent-introspection-debugging

或在支持直接引用 SKILL.md 的工具中直接加载该文件。

激活条件：当 Agent 运行失败、重复重试无进展、上下文异常膨胀、或工具调用超过阈值时，自动触发该 Skill。它不需要人工干预，在 Agent 意识到失败时就会启动四阶段流程。

使用场景与人群

适用场景：
– AI Coding Agent 在长时间任务中出现循环或 Token 消耗异常
– 自动化流水线中 Agent 因环境问题（端口、路径、服务状态）失败
– 需要对 Agent 行为进行审计或生成调试报告的开发团队
– 在生产环境中部署 Agent 前进行可靠性验证

目标用户：
– 日常使用 Claude Code、Codex、Cursor 等 AI 编程工具的开发者
– 搭建 AI Agent 自动化流水线的 DevOps / 平台工程师
– 对 AI Agent 生产级可靠性有要求的企业团队
– 研究 AI Agent 调试与自我修复能力的研究者

输入与输出案例

案例 1：循环失败

Input（Agent 触发）：

工具调用失败：同一命令被调用第 15 次，返回相同错误 “command not found”，上下文已达 180k token。

Agent 激活 Skill → Capture 记录：

## Failure Capture
- Session / task: 自动化测试流水线
- Goal in progress: 运行 pnpm test 并收集覆盖率报告
- Error: 重复工具调用 / command not found
- Last successful step: pnpm install 成功
- Last failed tool / command: pnpm test（第 15 次调用）
- Repeated pattern seen: 同一命令重复执行
- Environment assumptions to verify: pnpm 在 PATH 中、项目依赖已安装

Diagnose 匹配：Pattern = “Maximum tool calls / repeated same command”，Likely Cause = “loop or no-exit observer path”。

Recover：检查 pnpm 是否在 PATH → 确认 PATH 中无 pnpm → 改用 npx pnpm test。验证成功，测试通过，Token 消耗从 180k 降至 42k。

案例 2：上下文降级

Input（Agent 触发）：

上下文超过 200k token，输出质量明显下降，同一个 bug 修复了 3 次仍出现。

Agent 激活 Skill → Capture 发现：上下文中有 3 份重复的 Plan 文档、重复的错误分析段落、过大的粘贴日志。

Diagnose 匹配：Pattern = “Context overflow / degraded reasoning”，Likely Cause = “unbounded notes, repeated plans, oversized logs”。

Recover：裁剪重复内容，将上下文压缩至 85k，保留关键诊断信息。重新执行修复，一次通过。

GitHub: https://github.com/affaan-m/ECC