npx skills add https://github.com/boshu2/agentops --skill bug-hunt快速参考: 4阶段调查(根因 → 模式 → 假设 → 修复)。输出:
.agents/research/YYYY-MM-DD-bug-*.md
你必须执行此工作流。不要仅仅描述它。
系统化调查以找出根本原因并设计完整修复方案——或者主动审计以在隐藏的 bug 造成影响之前发现它们。
要求:
.agents/ 目录)| 模式 | 调用方式 | 适用场景 |
|---|---|---|
| 调查 | /bug-hunt <症状描述> | 你已知一个 bug 或故障 |
| 审计 |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
/bug-hunt --audit <范围>| 主动扫描以发现隐藏的 bug |
调查模式使用下面的 4 阶段结构。审计模式使用系统化的阅读和分类——参见审计模式。
| 阶段 | 重点 | 输出 |
|---|---|---|
| 1. 根因 | 找到实际的 bug 位置 | 文件:行号,提交 |
| 2. 模式 | 与工作示例进行比较 | 识别出的差异 |
| 3. 假设 | 形成并测试单一假设 | 每个假设的通过/失败 |
| 4. 实施 | 在根源处修复,而非症状 | 已验证的修复 |
关于故障分类法和 3 次失败规则,请阅读 skills/bug-hunt/references/failure-categories.md。
给定 /bug-hunt <症状描述>:
首先,复现问题:
仔细阅读错误信息。 不要跳过或略读。
如果无法复现 bug,请先收集更多信息再继续。
找到 bug 显现的位置:
# 搜索错误信息
grep -r "<错误文本>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
# 搜索函数/变量名
grep -r "<相关名称>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
查找 bug 是何时/如何被引入的:
# 文件最后一次更改是什么时候?
git log --oneline -10 -- <文件>
# 最近有什么变化?
git diff HEAD~10 -- <文件>
# 谁更改了它?为什么?
git blame <文件> | grep -A2 -B2 "<可疑行>"
# 搜索相关提交
git log --oneline --grep="<关键词>" | head -10
使用 TASK 工具 (subagent_type: "Explore") 来追踪执行路径:
基于追踪结果,识别:
在代码库中搜索功能相似但正常工作的代码:
# 查找相似模式
grep -r "<工作模式>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
识别以下两者之间的所有差异:
记录每个差异。
清晰地陈述你的假设:
"我认为 X 是错的,因为 Y"
一次只测试一个假设。 不要合并多个猜测。
进行最小可能的改动来测试假设:
根据 skills/bug-hunt/references/failure-categories.md 检查失败次数。在 3 次可计数的失败后,升级到架构评审。
在编写代码之前,先设计修复方案:
在修复 bug 之前,编写一个能演示该 bug 的测试。
在根因处修复,而不是在症状处。
运行失败的测试——它现在应该通过。
当使用 --audit 调用时,bug-hunt 切换到主动扫描模式。不需要症状描述——你正在寻找尚未被报告的 bug。
/bug-hunt --audit cli/internal/goals/ # 审计一个包
/bug-hunt --audit src/auth/ # 审计一个目录
/bug-hunt --audit . # 审计仓库中的近期更改
根据范围参数识别目标文件:
# 查找范围内的源文件
find <范围> -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | head -50
如果范围是 . 或范围过广(>50 个文件),则缩小到最近更改的文件:
git log --since="2 weeks ago" --name-only --pretty=format: -- <范围> | sort -u | head -30
逐行阅读范围内的每个文件。对于每个文件,检查:
| 类别 | 需要寻找的内容 |
|---|---|
| 资源泄漏 | 未关闭的句柄、孤儿进程、缺少清理/defer |
| 字符串安全 | UTF-8 的字节级截断、未净化的输入 |
| 死代码 | 不可达的分支、未使用的常量、被遮蔽的变量 |
| 硬编码值 | 路径、URL、特定仓库的假设(在其他地方无法工作) |
| 边界情况 | 空输入、nil/零值、边界条件 |
| 并发问题 | 未受保护的共享状态、goroutine 泄漏、缺少信号处理器 |
| 错误处理 | 被吞掉的错误、缺少上下文、错误的错误类型 |
关键纪律: 逐行阅读。不要略读。已验证的方法论(发现 5 个 bug,0 次假设失败)来自于仔细阅读,而非启发式扫描。
对于大范围——使用 TASK 工具 (subagent_type: "Explore") 将文件拆分给并行代理处理。
对于每个发现,分配严重性:
| 严重性 | 标准 | 示例 |
|---|---|---|
| 高 | 数据丢失、安全漏洞、资源泄漏、进程孤儿化 | 僵尸进程、SQL 注入、文件句柄泄漏 |
| 中 | 错误输出、不正确的默认值、静默数据损坏 | UTF-8 截断、硬编码路径、错误的错误代码 |
| 低 | 死代码、外观问题、轻微不一致 | 不可达分支、未使用的导入、风格违规 |
关于审计报告格式,请阅读 skills/bug-hunt/references/audit-report-template.md。
写入 .agents/research/YYYY-MM-DD-bug-<范围-标识>.md。
向用户报告,并附带摘要表格:
| # | Bug | 严重性 | 文件 | 修复建议 |
|---|-----|----------|------|-----|
| 1 | <描述> | 高 | <文件:行号> | <建议的修复> |
包含失败计数(未得到确认的假设测试)。零失败 = 干净的审计。
关于 bug 报告模板,请阅读 skills/bug-hunt/references/bug-report-template.md。
告知用户:
常见的 bug 模式检查:
用户说: /bug-hunt "CI 上测试失败但本地通过"
过程:
.agents/research/2026-02-13-bug-test-failure.md结果: 根因识别为 CI 配置中缺少 ENV 变量。修复已应用并验证。
用户说: /bug-hunt "功能 X 在昨天的部署后失效"
过程:
git log --since="2 days ago" 查找最近的提交git bisect 识别确切的破坏性提交结果: 回归问题追溯到提交 abc1234,验证逻辑中的类型转换错误在根因处修复。
用户说: /bug-hunt --audit cli/internal/goals/
过程:
.go 文件.agents/research/2026-02-24-bug-goals-go.md结果: 5 个具体的 bug,附带严重性、文件:行号和建议的修复——无需调试即可准备实施。
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 无法复现 bug | 环境上下文不足或间歇性问题 | 向用户询问具体步骤、环境变量、输入数据。检查竞态条件或时序问题。 |
| Git 考古返回过多提交 | 搜索范围过广或文件变更频繁 | 使用 --since 标志缩小时间范围,使用 git blame 聚焦特定函数,在提交信息中搜索相关关键词。 |
| 假设测试期间达到 3 次失败限制 | 多个错误假设或复杂的根因 | 升级到架构评审。阅读 failure-categories.md 以确定失败是否可计数。考虑请求领域专家输入。 |
| Bug 报告缺少关键信息 | 调查不完整或跳过了步骤 | 验证所有 4 个阶段均已完成。确保已识别根因并附带文件:行号。检查是否运行了 git blame 以找到责任提交。 |
每周安装次数
234
仓库
GitHub 星标数
197
首次出现
2026年2月2日
安全审计
安装于
opencode230
codex229
gemini-cli227
github-copilot226
amp222
kimi-cli222
Quick Ref: 4-phase investigation (Root Cause → Pattern → Hypothesis → Fix). Output:
.agents/research/YYYY-MM-DD-bug-*.md
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Systematic investigation to find root cause and design a complete fix — or proactive audit to find hidden bugs before they bite.
Requires:
.agents/ directories for output)| Mode | Invocation | When |
|---|---|---|
| Investigation | /bug-hunt <symptom> | You have a known bug or failure |
| Audit | /bug-hunt --audit <scope> | Proactive sweep for hidden bugs |
Investigation mode uses the 4-phase structure below. Audit mode uses systematic read-and-classify — see Audit Mode.
| Phase | Focus | Output |
|---|---|---|
| 1. Root Cause | Find the actual bug location | file:line, commit |
| 2. Pattern | Compare against working examples | Differences identified |
| 3. Hypothesis | Form and test single hypothesis | Pass/fail for each |
| 4. Implementation | Fix at root, not symptoms | Verified fix |
For failure category taxonomy and the 3-failure rule, readskills/bug-hunt/references/failure-categories.md.
Given /bug-hunt <symptom>:
First, reproduce the issue:
Read error messages carefully. Do not skip or skim them.
If the bug can't be reproduced, gather more information before proceeding.
Find where the bug manifests:
# 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
Find when/how the bug was introduced:
# 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
USE THE TASK TOOL (subagent_type: "Explore") to trace the execution path:
Based on tracing, identify:
Search the codebase for similar functionality that WORKS:
# Find similar patterns
grep -r "<working-pattern>" . --include="*.py" --include="*.ts" --include="*.go" 2>/dev/null | head -10
Identify ALL differences between:
Document each difference.
State your hypothesis clearly:
"I think X is wrong because Y"
One hypothesis at a time. Do not combine multiple guesses.
Make the SMALLEST possible change to test the hypothesis:
Check failure count per skills/bug-hunt/references/failure-categories.md. After 3 countable failures, escalate to architecture review.
Before writing code, design the fix:
Write a test that demonstrates the bug BEFORE fixing it.
Fix at the ROOT CAUSE, not at symptoms.
Run the failing test - it should now pass.
When invoked with --audit, bug-hunt switches to a proactive sweep. No symptom needed — you're hunting for bugs that haven't been reported yet.
/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
Identify target files from the scope argument:
# Find source files in scope
find <scope> -name "*.go" -o -name "*.py" -o -name "*.ts" -o -name "*.rs" | head -50
If scope is . or broad (>50 files), narrow to recently changed files:
git log --since="2 weeks ago" --name-only --pretty=format: -- <scope> | sort -u | head -30
Read every file in scope line by line. For each file, check:
| Category | What to Look For |
|---|---|
| Resource Leaks | Unclosed handles, orphaned processes, missing cleanup/defer |
| String Safety | Byte-level truncation of UTF-8, unsanitized input |
| Dead Code | Unreachable branches, unused constants, shadowed variables |
| Hardcoded Values | Paths, URLs, repo-specific assumptions that won't work elsewhere |
| Edge Cases | Empty input, nil/zero values, boundary conditions |
| Concurrency | Unprotected shared state, goroutine leaks, missing signal handlers |
| Error Handling | Swallowed errors, missing context, wrong error types |
Key discipline: Read line by line. Do not skim. The proven methodology (5 bugs found, 0 hypothesis failures) came from careful reading, not heuristic scanning.
USE THE TASK TOOL (subagent_type: "Explore") for large scopes — split files across parallel agents.
For each finding, assign severity:
| Severity | Criteria | Examples |
|---|---|---|
| HIGH | Data loss, security, resource leak, process orphaning | Zombie processes, SQL injection, file handle leak |
| MEDIUM | Wrong output, incorrect defaults, silent data corruption | UTF-8 truncation, hardcoded paths, wrong error code |
| LOW | Dead code, cosmetic, minor inconsistency | Unreachable branch, unused import, style violation |
For audit report format, readskills/bug-hunt/references/audit-report-template.md.
Write to .agents/research/YYYY-MM-DD-bug-<scope-slug>.md.
Report to user with a summary table:
| # | Bug | Severity | File | Fix |
|---|-----|----------|------|-----|
| 1 | <description> | HIGH | <file:line> | <proposed fix> |
Include failure count (hypothesis tests that didn't confirm). Zero failures = clean audit.
For bug report template, readskills/bug-hunt/references/bug-report-template.md.
Tell the user:
Common bug patterns to check:
User says: /bug-hunt "tests failing on CI but pass locally"
What happens:
.agents/research/2026-02-13-bug-test-failure.mdResult: Root cause identified as missing ENV variable in CI configuration. Fix applied and verified.
User says: /bug-hunt "feature X broke after yesterday's deployment"
What happens:
git log --since="2 days ago" to find recent commitsgit bisect to identify exact breaking commitResult: Regression traced to commit abc1234, type conversion error fixed at root cause in validation logic.
User says: /bug-hunt --audit cli/internal/goals/
What happens:
.go files in the goals package.agents/research/2026-02-24-bug-goals-go.mdResult: 5 concrete bugs with severity, file:line, and proposed fix — ready for implementation without debugging.
| Problem | Cause | Solution |
|---|---|---|
| Can't reproduce bug | Insufficient environment context or intermittent issue | Ask user for specific steps, environment variables, input data. Check for race conditions or timing issues. |
| Git archaeology returns too many commits | Broad search or high-churn file | Narrow timeframe with --since flag, focus on specific function with git blame, search commit messages for related keywords. |
| Hit 3-failure limit during hypothesis testing | Multiple incorrect hypotheses or complex root cause | Escalate to architecture review. Read failure-categories.md to determine if failures are countable. Consider asking for domain expert input. |
| Bug report missing key information | Incomplete investigation or skipped steps | Verify all 4 phases completed. Ensure root cause identified with file:line. Check git blame ran for responsible commit. |
Weekly Installs
234
Repository
GitHub Stars
197
First Seen
Feb 2, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode230
codex229
gemini-cli227
github-copilot226
amp222
kimi-cli222
xdrop 文件传输脚本:Bun 环境下安全上传下载工具,支持加密分享
20,700 周安装