hello-debug

Agent Skills › hellowind777/helloagents › hello-debug

hello-debug

GitHub

提供系统化调试规范，涵盖根因分析、反馈循环建立、四阶段调试法及升级策略。旨在通过Git历史追踪、假设验证和最小修复原则，高效排查故障并防止回归。

skills/hello-debug/SKILL.md hellowind777/helloagents

Trigger Scenarios

调试错误修复 bug 排查失败测试处理异常行为代码行为与预期不符

Install

npx skills add hellowind777/helloagents --skill hello-debug -g -y

More Options

Use without installing

npx skills use hellowind777/helloagents@hello-debug

指定 Agent (Claude Code)

npx skills add hellowind777/helloagents --skill hello-debug -a claude-code -g -y

安装 repo 全部 skill

npx skills add hellowind777/helloagents --all -g -y

预览 repo 内 skill

npx skills add hellowind777/helloagents --list

SKILL.md

Frontmatter

{
    "name": "hello-debug",
    "description": "调试错误、修复 bug、排查失败测试、处理异常行为，或代码行为与预期不符时使用。"
}

调试相关工作必须遵循以下规范。

编码前

禁止未经根因分析直接修复。先建立可运行、可重复、可判断的反馈循环；没有反馈循环，不直接猜原因或改代码。

Git 作为记忆

每次调试前，先读取相关的 git 历史：

git log --oneline -20 查看最近变更
git log --all --grep="revert" 查看过去的失败回滚
如果发现之前已经尝试并回滚过类似修复 → 不要重复同样的方向

反馈循环优先

反馈循环是调试入口，必须能证明“问题出现 / 问题消失”：

优先写失败测试；不适合写测试时，用 HTTP 脚本、CLI 样例输入、浏览器脚本、请求 / 事件回放、最小验证脚本、差异对比或压力循环复现
循环要尽量快、稳定、断言具体症状，不用“没有崩溃”代替正确性
非确定性问题先提高复现率，记录触发次数、失败比例和关键条件
实在无法建立循环时，停止并说明已尝试方式，向用户请求日志、录屏、请求记录、环境访问或授权加临时观测点

四阶段调试法

1. 定位

完整读取错误信息（不截断、不猜测）
用反馈循环稳定复现问题（确定触发条件）
反向追踪数据流（从错误点向上游追溯）

2. 分析

找到类似的正常工作代码，对比差异
检查最近的变更（git log/diff）
识别所有隐含假设

3. 假设

形成 3-5 个按可能性排序的假设
每个假设必须可证伪：写清“如果原因是 X，那么改变或观测 Y 会出现 Z”
单变量测试（一次只改一个东西）
记录每次尝试和结果

4. 修复

先写失败测试复现 bug
实现最小修复（针对根因，不是症状）
验证修复有效且无回归

临时观测点

临时日志必须带唯一前缀，如 [DEBUG-a4f2]
禁止“到处打印再搜索”；每个观测点都要对应一个假设
收尾前搜索前缀，删除所有临时日志、临时验证脚本和实验文件；确需保留时移动到明确的 debug 目录并说明原因

卡住升级机制

连续修复失败时，按以下阶梯升级策略：

第 1-2 次失败：正常反思，调整修复方向第 3 次失败：停止。3 次失败意味着可能是架构问题而非局部 bug。重新从根因分析开始，质疑当前方向是否正确第 4 次失败：扩大范围——重读所有相关文件，审查 git 历史中的相关变更，检查是否有隐藏的依赖或副作用第 5 次失败：必须与用户讨论。提出以下选项：