bug-hunt-swarm

Bug Hunt Swarm

并行派遣 4 个只读子 Agent 调查 Bug，然后由主 Agent 对可能的原因排序，并建议最快的验证或修复路径。这项技能以诊断为先：在此工作流中，不要编辑文件或实施修复。

Step 1：整理 Bug 信息包

首先收集一份尽可能精简且有用的调查信息包：

1. 症状
2. 预期行为
3. 实际行为
4. 复现步骤（如已知）
5. 影响范围
6. 相关证据，例如日志、堆栈跟踪、失败的测试、截图、近期差异或环境详情

优先按以下顺序查找信息来源：

1. 用户的直接描述
2. 用户提供的明确文件、堆栈跟踪、日志、测试或截图
3. 当 Bug 看起来像是回归问题时，当前的 Git 变更或近期仓库历史
4. 故障附近最小范围内的相关代码路径或子系统

如果 Bug 报告信息不足，请推断出最精简的问题描述，并说明仍有哪些未知之处。

启动子 Agent 前，请阅读最贴近问题的项目说明，以及受影响部分的相关文档，例如：

• AGENTS.md
• 仓库工作流文档
• 受影响子系统的架构、状态、路由、架构定义或运行时文档

Step 2：限定调查范围

为整个调查组撰写一份简短的调查说明：

1. 哪些部分看起来无法正常工作
2. 哪些内容尚未得到证实
3. 系统中最可能涉及的部分
4. 已有的证据
5. 哪类证据可作为确认依据

在适当情况下，使用只读方式收集证据：

• rg、git diff、git log、git show
• 阅读日志、崩溃跟踪和配置
• 运行已有测试，或执行最小且安全的复现命令

此技能中不要编辑文件、添加新的检测代码或实施修复。

Step 3：并行启动 4 个只读调查员

当问题足够复杂或模糊，且并行调查会有所帮助时，启动 4 个子 Agent。对于微小且明显的问题，也可以在本地调查。

对每个子 Agent：

• 提供相同的 Bug 信息包和调查说明
• 明确说明该子 Agent 只能只读操作
• 不允许子 Agent 编辑文件、运行 apply_patch、暂存变更、提交变更或执行任何其他会改变状态的操作
• 只要求其简洁地输出调查结果
• 要求提供：假设、支持证据、缺失证据、最小验证步骤和置信度
• 告知子 Agent 避免泛泛的代码质量反馈、吹毛求疵，或没有证据支撑的推测
• 告知子 Agent 仅向主 Agent反馈调查结果

使用以下 4 种调查角色。

子 Agent 1：复现与范围调查

明确故障的具体表现和边界。

检查：

1. 范围最窄且可靠的触发条件
2. 会导致 Bug 出现或消失的条件
3. 故障边界处的预期行为与实际行为
4. 影响是局部的、跨领域的、确定性的，还是不稳定的

此子 Agent 只能只读操作。不得编辑文件、应用补丁或进行任何其他工作区更改。

建议的子 Agent 角色：reviewer

子 Agent 2：代码路径与故障衔接点调查

跟踪最可能的执行路径，并找出行为出现偏差的衔接点。

检查：

1. 状态转换、生命周期边界或顺序问题
2. 调用方与被调用方之间不一致的假设
3. 数据流或控制流中断
4. 最可能导致故障的最小代码区域

此子 Agent 只能只读操作。不得编辑文件、应用补丁或进行任何其他工作区更改。

建议的子 Agent 角色：广泛跟踪时使用 explorer，需要更深入地推理局部问题时使用 reviewer

子 Agent 3：近期变更与回归调查

在近期历史记录或变更的契约中查找可能引入回归的因素。

检查以下内容：

1. 与症状相关的近期差异
2. 配置、标志、依赖项、架构或迁移方面的偏移
3. 多个入口点本应同时变更，但只更新了部分入口点
4. 符合错误报告时间节点的行为变更

此子 Agent 仅可读取。不得编辑文件、应用补丁或以任何其他方式更改工作区。

推荐的子 Agent 角色：reviewer

子 Agent 4：验证方案与可观测性调查

确定确认或排除主要假设的最快方法。

检查以下内容：

1. 应当失败的最小现有测试或复现用例
2. 最有用的现有日志、跟踪记录、指标或断言
3. 能快速提高置信度的最小非变更命令
4. 缺少哪些证据，以及如何在避免大范围变更的情况下收集这些证据

此子 Agent 仅可读取。不得编辑文件、应用补丁或以任何其他方式更改工作区。

推荐的子 Agent 角色：reviewer

只报告能显著提高找到真正原因概率的假设。与其给出 6 个含糊的猜测，不如提供 2 个有证据支持的理论。

第 4 步：综合并排列假设

综合工作由主 Agent 负责。将子 Agent 的输出视为原始调查材料，而非最终输出。

合并并排列假设：

• 合并重复项
• 舍弃依据薄弱的推测
• 优先考虑证据，而非表述是否漂亮
• 区分可能的根本原因与仅起促成作用的因素
• 仅在其他理论仍有可能时保留备选理论

将筛选后保留的假设整理为以下格式：

1. 假设
2. 支持证据
3. 缺失或相矛盾的证据
4. 最小验证步骤
5. 置信度：高、中或低

如果证据不足以进行有效排序，请直接说明，并列出当前最值得追查的问题。

第 5 步：给出清晰的诊断路径

按以下顺序呈现结果：

1. 最可能的根本原因
2. 可能的备选原因（如有）
3. 最快的验证步骤
4. 建议的修复路径
5. 未解问题或阻碍因素

如果尚不清楚如何修复，请建议下一步验证工作，而不要假装诊断已经完成。

必要时，可将行动分为：

• 立即验证
• 接下来修复
• 后续跟进

不得将修复作为此技能的一部分来实施。输出应为只读诊断，并提供优先级明确的后续路径。