jackwener /hunt · Bug 系统化根因排查
使用场景
- 报 bug：某个功能不 work / 行为不符合预期
- 测试失败：某个 test case 红了
- 回归：之前能跑的现在不能跑
- 线上异常：日志里出现错误堆栈
目标
找到根因再动手——Agent 默认倾向于"看起来像 bug 就直接改"，结果往往是 patch 表面、留下根因不改，下次再以另一种形态复现。
必须步骤
1. 复现
- 先把 bug 稳定复现——给出最小复现路径（命令 / 步骤 / 输入）
- 如果暂时不能复现：说明"目前无法稳定复现"，不允许直接开始修
- 复现的同时把环境信息记下来：Node 版本、依赖版本、env 变量、相关日志
2. 定位最近变更
git log --oneline -20看最近 commitgit blame关注嫌疑代码的最近修改- 找出疑似引入 bug 的 commit / PR
3. 提出假设
至少提 2 个假设。每个假设要回答：
- 它如何解释观察到的现象？
- 怎么验证它（验证方法必须可执行：跑命令 / 加 log / 改测试）？
- 如果假设成立，最小修复方案是什么？
4. 逐个验证假设
按"成本低的假设先验"的顺序。每验证一个：
- 通过 → 进入修复阶段
- 证伪 → 记录"为什么不是"，转下一个
5. 修复（仅在根因确认后）
修完后：
- 跑一遍原始复现路径——bug 应消失
- 加 1 个测试用例复现 + 修复证据（防回归）
- 在
gotchas.md记一条"踩坑：xxx + 根因 yyy + 防回归方法 zzz"
禁止事项
- ❌ 未确认根因前不允许动代码
- ❌ 不允许用"反正这样改了就好了"作为根因
- ❌ 不允许删除 / 跳过让你不舒服的测试用例
- ❌ 不允许用
--no-verify绕过 pre-commit 检查 - ❌ 不允许把"workaround"包装成"修复"（如必须 workaround，明确标注
// TODO: workaround for X）
输出格式
## 现象
- 期望：...
- 实际：...
- 复现路径：...
## 最近变更
- 嫌疑 commit：abc1234（PR #N）
- 修改了：xxx
## 假设
### H1：...
- 为何成立：...
- 验证：跑 `xxx`
- 修复方向：...
### H2：...
（同上）
## 验证结果
- H1：证伪。理由：...
- H2：成立。证据：...
## 根因
（一两句话）
## 修复
- 改动：...
- 防回归：新增测试 `xxx.test.ts`，确保未来同类 bug 不再出现
## 验证
- 命令：`pnpm test`，全过 ✓
- 手测：原始复现路径不再触发
与其他 Skill 的关系
- 修复方案确定后用
/small-diff控制改动范围 - 完成后用
/check审查 diff 是否引入新问题 - 新发现的边界 case 用
/update-context写入 gotchas