bug-hunt

Bug Hunt 技能

**快速参考：**4 阶段调查（根因 → 模式 → 假设 → 修复）。输出：.agents/research/YYYY-MM-DD-bug-*.md

你必须执行此工作流。不要只描述它。

通过系统调查查找根因并设计完整修复方案，或主动审计，在隐藏的 Bug 造成影响前将其找出。

需要：

• 可写入的 .agents/ 输出目录；若不存在，请显式创建
• 如需创建后续问题，则需要用于问题跟踪的 bd CLI（beads）

模式

模式	调用方式	适用场景
调查	/bug-hunt <symptom>	已知存在 Bug 或故障
审计	/bug-hunt --audit <scope>	主动排查隐藏的 Bug

调查模式使用以下 4 阶段结构。审计模式使用系统化的读取与分类方法——请参阅审计模式。

---

4 阶段结构（调查模式）

阶段	重点	输出
1. 根因	找到实际 Bug 所在位置	文件:行号、提交
2. 模式	与正常工作的示例进行比较	已识别的差异
3. 假设	提出并测试单一假设	每项测试的通过/失败结果
4. 实施	从根源修复，而非只处理症状	已验证的修复

关于故障类别分类和 3 次失败规则，请阅读 skills/bug-hunt/references/failure-categories.md。

对于需要多轮排查的审计或发布前扫描，请通过 skills/bug-hunt/references/audit-fix-rescan-cycle.md（多轮方法）进行，并使用 skills/bug-hunt/references/convergence-criteria.md 决定何时停止。

对于需要以全新视角重新扫描的主动排查，还需加载 references/multi-pass-bug-hunting.md。

对于卡住的命令、死锁、重试风暴、被阻塞的子进程或挂起，请在更改代码前加载 references/deadlock-and-hang-triage.md。

当目标进程正在运行、已挂起，或仅在调试器监视时才能重现时，请在附加调试器或更改 ptrace/sysctl 设置前加载 references/debugger-attach-triage.md。

执行步骤

给定 /bug-hunt <symptom>：

---

步骤 0：加载此前的 Bug 上下文

开始调查前，检查此代码库区域是否有此前的经验记录：

if command -v ao &>/dev/null; then
    ao lookup --query "<symptom-keywords> bug patterns" --limit 3 2>/dev/null || true
fi

**应用检索到的知识：**如果返回了经验记录，请逐条检查其是否适用于当前 Bug。对于适用的经验记录（例如，同一区域此前发生的 Bug、已知的脆弱模式），将其作为调查线索，并注明文件名。记录：ao metrics cite "<path>" --type applied 2>/dev/null || true

此前的 Bug 报告、修复模式和已知脆弱区域可缩短调查时间。

---

阶段 1：根因调查

步骤 1.1：确认 Bug

首先，重现问题：

• 预期行为是什么？
• 实际行为是什么？
• 能否稳定重现？

**仔细阅读错误消息。**不要跳过或略读。

如果无法重现 Bug，请先收集更多信息再继续。

步骤 1.2：定位症状

找到 Bug 显现的位置：

# Search for error messages
grep -r "<error-text>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

# Search for function/variable names
grep -r "<relevant-name>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

步骤 1.3：Git 考古

查明 Bug 是何时以及如何引入的：

# When was the file last changed?
git log --oneline -10 -- <file>

# What changed recently?
git diff HEAD~10 -- <file>

# Who changed it and why?
git blame <file> | grep -A2 -B2 "<suspicious-line>"

# Search for related commits
git log --oneline --grep="<keyword>" | head -10

步骤 1.4：追踪执行路径

使用 TASK 工具（subagent_type: "Explore"）追踪执行路径：

• 找到 Bug 显现处的入口点
• 向前追踪，查明错误数据/状态的来源
• 识别路径中的所有函数以及它们最近的更改
• 返回：执行路径、可能的根因位置、相关更改

步骤 1.5：确定根因

根据追踪结果，确定：

• 问题是什么（实际 Bug）
• 位置在哪里（文件:行号）
• 引入时间（提交）
• 原因是什么（逻辑错误）

---

阶段 2：模式分析

步骤 2.1：查找正常工作的示例

在代码库中搜索功能相似且正常工作的示例：

# Find similar patterns
grep -r "<working-pattern>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10

第 2.2 步：与参考版本对比

找出以下两者之间的所有差异：

• 有问题的代码
• 可正常工作的参考版本

记录每一处差异。

---

第 3 阶段：提出假设并测试

第 3.1 步：提出单一假设

清楚地陈述你的假设：

“我认为 X 有问题，因为 Y”

一次只提出一个假设。 不要把多个猜测合并在一起。

第 3.2 步：进行最小改动测试

进行尽可能小的改动来测试假设：

• 如果有效 → 继续进入第 4 阶段
• 如果无效 → 记录失败，并提出新假设

第 3.3 步：检查失败次数

根据 skills/bug-hunt/references/failure-categories.md 检查失败次数。出现 3 次可计数的失败后，升级至架构审查。

---

第 4 阶段：实施

第 4.1 步：设计修复方案

编写代码前，先设计修复方案：

• 需要做出哪些改动？
• 有哪些边缘情况？
• 此修复会导致其他问题吗？
• 是否需要更新测试？

第 4.2 步：创建失败测试（如果可能）

修复前，编写一个能复现该错误的测试。

第 4.3 步：实施单一修复

修复根本原因，而不是表面症状。

第 4.4 步：验证修复

运行之前失败的测试——现在应该能够通过。

如果问题出在复杂度很高的函数中，可在修复后考虑使用 /refactor，以防问题再次发生。

---

审计模式

使用 --audit 调用时，bug-hunt 会切换到主动扫描模式。无需提供症状——你要主动寻找尚未报告的问题。

/bug-hunt --audit cli/internal/goals/     # audit a package
/bug-hunt --audit src/auth/               # audit a directory
/bug-hunt --audit .                        # audit recent changes in repo

审计步骤 1：确定范围

根据范围参数确定目标文件：

# Find source files in scope
find <scope> -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | head -50

如果范围是 . 或较广（>50 个文件），则缩小范围，仅检查最近更改的文件：

git log --since="2 weeks ago" --name-only --pretty=format: -- <scope> | sort -u | head -30

审计步骤 2：系统性阅读

逐行阅读范围内的每个文件。对每个文件，检查：

类别	检查内容
资源泄漏	未关闭的句柄、孤立进程、缺少清理或 defer
字符串安全	UTF-8 的字节级截断、未经净化的输入
死代码	不可达分支、未使用的常量、被遮蔽的变量
硬编码值	在其他环境中无法使用的路径、URL、特定于仓库的假设
边缘情况	空输入、nil/零值、边界条件
并发	未受保护的共享状态、goroutine 泄漏、缺少信号处理程序
错误处理	被忽略的错误、缺少上下文、错误类型不匹配

关键纪律： 逐行阅读，不要略读。经验证的方法（发现 5 个错误，假设测试失败 0 次）依靠的是仔细阅读，而非启发式扫描。

对于较大的范围，使用 TASK TOOL（subagent_type: "Explore"）——将文件分配给多个并行 Agent。

审计步骤 3：对发现的问题分类

为每项发现的问题指定严重程度：

严重程度	判定标准	示例
高	数据丢失、安全问题、资源泄漏、进程孤立	僵尸进程、SQL 注入、文件句柄泄漏
中	输出错误、默认值不正确、静默数据损坏	UTF-8 截断、硬编码路径、错误代码不正确
低	死代码、外观问题、轻微不一致	不可达分支、未使用的导入、样式违规

性能问题（查询缓慢、内存泄漏、N+1）→ 升级到 /perf 进行深入分析。

审计步骤 4：撰写审计报告

审计报告的格式请参阅 skills/bug-hunt/references/audit-report-template.md。

写入 .agents/research/YYYY-MM-DD-bug-<scope-slug>.md。

向用户汇报时附上摘要表：

| # | Bug | Severity | File | Fix |
|---|-----|----------|------|-----|
| 1 | <description> | HIGH | <file:line> | <proposed fix> |

注明失败次数（未能证实假设的测试次数）。失败次数为 0 表示审计未发现问题。

Bug-Finding Pyramid 模式（BF1–BF5）

运行 --audit 时，检查是否缺少 bug 查找测试覆盖：

BF4 — 混沌/负向测试（bug 查找能力最高）： 对于每个会进行外部调用（API、数据库、文件系统）的文件，验证：

• 存在超时注入测试
• 存在连接失败测试
• 存在权限拒绝测试
• 存在输入损坏测试

如果任何边界缺少故障注入 → 将其标记为发现项（严重程度：显著）。

BF5 — 脚本功能测试： 对于每个调用外部工具（oc、kubectl、helm）的 .sh 脚本：

• 存在基于桩的功能测试
• 已验证 JSON 输出架构
• 已测试正常和异常的桩路径

如果脚本缺少功能测试 → 将其标记为发现项（严重程度：中等）。

BF1 — 基于属性的测试： 对于每个数据转换（解析/渲染/序列化）：

• 存在使用随机输入的属性测试

参考： /standards 中的测试金字塔标准，包含完整的 BF 级别定义和各语言的工具。

---

步骤 5：编写 Bug 报告

Bug 报告模板请参阅 skills/bug-hunt/references/bug-report-template.md。

步骤 6：向用户报告

告知用户：

1. 已确定根本原因（或尚未确定）
2. Bug 位置（文件:行号）
3. 建议的修复方案
4. Bug 报告的位置
5. 遇到的失败次数和类型
6. 下一步：实施修复或收集更多信息

关键规则

• 先复现——确认 bug 确实存在
• 追溯 Git 历史——了解历史变更
• 系统地追踪——沿执行路径排查
• 找出根本原因——不只看表面症状
• 先设计再修复——仔细考虑解决方案
• 记录发现——编写 bug 报告

快速检查

需要检查的常见 bug 模式：

• 差一错误
• Null/undefined 处理
• 竞态条件
• 类型不匹配
• 缺少错误处理
• 状态未重置
• 缓存问题

示例

调查测试失败

用户说： /bug-hunt "tests failing on CI but pass locally"

处理过程：

1. Agent 对比 CI 日志与本地测试输出，确认 bug
2. Agent 通过追溯 Git 历史，查找近期对测试文件的更改
3. Agent 沿执行路径追踪，找出环境差异
4. Agent 推测缺少环境变量
5. Agent 通过取消设置该变量，在本地创建失败测试
6. Agent 添加默认值来实施修复
7. Bug 报告写入 .agents/research/2026-02-13-bug-test-failure.md

结果： 已确定根本原因是 CI 配置中缺少 ENV 变量。修复已应用并验证。

排查回归问题

用户说： /bug-hunt "feature X broke after yesterday's deployment"

处理过程：

1. Agent 在当前状态下复现问题
2. Agent 使用 git log --since="2 days ago" 查找近期提交
3. Agent 使用 git bisect 找出确切的故障提交
4. Agent 将损坏的代码与代码库中的正常示例进行比较
5. Agent 推测问题由引入的类型不匹配导致
6. Agent 实施最小修复，并通过现有测试验证
7. Bug 报告记录提交 sha、根本原因和修复方案

结果： 回归问题追溯到提交 abc1234，验证逻辑中的类型转换错误已从根本上修复。

主动代码审计

用户说： /bug-hunt --audit cli/internal/goals/

处理过程：

1. Agent 将范围限定为 goals 包中的所有 .go 文件
2. Agent 逐行阅读每个文件，检查资源泄漏、字符串安全性、死代码等
3. Agent 发现 5 个 bug：僵尸进程组（HIGH）、UTF-8 截断（MEDIUM）、硬编码路径（MEDIUM）、段落分隔符丢失（LOW）、死分支（LOW）
4. 所有发现均在第一轮得到确认——假设失败数为 0
5. 审计报告写入 .agents/research/2026-02-24-bug-goals-go.md

结果： 发现 5 个具体 bug，并标注严重程度、文件:行号和建议修复方案——无需调试即可开始实施。

故障排查

问题	原因	解决方案
无法复现 Bug	环境上下文不足，或问题偶发	请用户提供具体步骤、环境变量和输入数据。检查是否存在竞态条件或时序问题。
Git 历史检索返回的提交过多	搜索范围过宽，或文件变更频繁	使用 --since 标志缩小时间范围，使用 git blame 聚焦特定函数，并搜索提交消息中的相关关键词。
假设测试期间达到 3 次失败上限	多个假设不正确，或根因较复杂	升级至架构评审。阅读 failure-categories.md，判断这些失败是否计入次数。考虑征询领域专家的意见。
Bug 报告缺少关键信息	调查不完整，或跳过了步骤	确认已完成全部 4 个阶段。确保已通过文件:行号确定根因。检查是否对相关提交运行了 git blame。

参考文档

• references/bug-hunt.feature — 可执行规范：4 阶段根因调查、修复原因而非症状、--audit 全面检查、引用的工件（soc-qk4b）

• references/audit-report-template.md

• references/bug-report-template.md

• references/failure-categories.md

• references/audit-fix-rescan-cycle.md

• references/convergence-criteria.md

• references/multi-pass-bug-hunting.md

• references/deadlock-and-hang-triage.md

• references/debugger-attach-triage.md

另请参阅

• refactor — 针对复杂且易出 Bug 的代码进行安全重构
• perf — 针对性能相关 Bug 进行性能分析