# Hunt

> Bug 系统化排查。给定问题描述后先复现 → 定位 → 提假设 → 验证 → 再决定怎么修。任何 bug、回归、线上异常、"为什么不 work" 类问题开始前必须执行。

- Skill: `jackwener/hunt` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jackwener/hunt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jackwener/hunt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jackwener (https://skillmd.com/u/jackwener)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jackwener/hunt

---


# /hunt · Bug 系统化根因排查

## 使用场景

- 报 bug：某个功能不 work / 行为不符合预期
- 测试失败：某个 test case 红了
- 回归：之前能跑的现在不能跑
- 线上异常：日志里出现错误堆栈

## 目标

**找到根因再动手**——Agent 默认倾向于"看起来像 bug 就直接改"，结果往往是 patch 表面、留下根因不改，下次再以另一种形态复现。

## 必须步骤

### 1. 复现

- 先把 bug **稳定复现**——给出最小复现路径（命令 / 步骤 / 输入）
- 如果暂时不能复现：说明"目前无法稳定复现"，**不允许**直接开始修
- 复现的同时把环境信息记下来：Node 版本、依赖版本、env 变量、相关日志

### 2. 定位最近变更

- `git log --oneline -20` 看最近 commit
- `git 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`）

## 输出格式

```markdown
## 现象
- 期望：...
- 实际：...
- 复现路径：...

## 最近变更
- 嫌疑 commit：abc1234（PR #N）
- 修改了：xxx

## 假设
### H1：...
- 为何成立：...
- 验证：跑 `xxx`
- 修复方向：...

### H2：...
（同上）

## 验证结果
- H1：证伪。理由：...
- H2：成立。证据：...

## 根因
（一两句话）

## 修复
- 改动：...
- 防回归：新增测试 `xxx.test.ts`，确保未来同类 bug 不再出现

## 验证
- 命令：`pnpm test`，全过 ✓
- 手测：原始复现路径不再触发
```

## 与其他 Skill 的关系

- 修复方案确定后用 [`/small-diff`](../small-diff/SKILL.md) 控制改动范围
- 完成后用 [`/check`](../check/SKILL.md) 审查 diff 是否引入新问题
- 新发现的边界 case 用 [`/update-context`](../update-context/SKILL.md) 写入 gotchas