reproduce-bug

重现 Bug

一种与框架无关、以假设为驱动的工作流，用于根据问题报告重现并调查 Bug。适用于任何语言、框架或项目类型。

阶段 1：了解问题

在接触代码库之前，先获取并分析 Bug 报告，提取结构化信息。

获取问题

如果未提供问题编号或 URL 作为参数，请先向用户索取，然后再继续（使用平台的提问工具，例如 Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user，或显示提示并等待回复）。

gh issue view $ARGUMENTS --json title,body,comments,labels,assignees

如果参数是 URL 而非编号，请提取问题编号，或将 URL 直接传给 gh。

提取关键信息

阅读问题及评论，然后识别以下内容：

• 报告的症状——用户观察到的情况（错误消息、错误输出、视觉异常、崩溃）
• 预期行为——本应发生的情况
• 重现步骤——报告者提供的任何步骤
• 环境线索——浏览器、操作系统、版本、用户角色、数据条件
• 发生频率——始终可重现、偶尔发生，还是仅发生一次

如果问题缺少重现步骤或描述含糊，请记录缺失的信息——这会影响调查策略。

阶段 2：提出假设

运行任何内容之前，先对根本原因提出假设。这能让调查更有针对性，避免漫无目的地探索。

搜索相关代码

使用原生内容搜索工具（例如 Claude Code 中的 Grep）查找与报告症状相关的代码路径。搜索以下内容：

• 问题中提到的错误消息或字符串
• 报告中描述的功能名称、路由路径或 UI 标签
• 相关的模型／服务／控制器名称

提出假设

根据问题详情和代码搜索结果，写下 2-3 个合理的假设。每个假设都应指出：

• 可能的问题（例如，“会话刷新时存在竞争条件”“可选字段缺少 nil 检查”）
• 代码库中的位置（具体文件和行范围）
• 为何会导致报告的症状

按可能性对假设排序。先调查最有可能的一项。

阶段 3：重现

尝试触发 Bug。重现策略取决于 Bug 类型。

路径 A：基于测试的重现（后端、逻辑、数据类 Bug）

编写或查找现有测试，以覆盖可疑代码路径：

1. 使用原生文件搜索工具（例如 Claude Code 中的 Glob）查找覆盖受影响代码的现有测试文件
2. 运行现有测试，查看是否已有测试失败
3. 如果没有测试覆盖该场景，则编写一个最小失败测试来演示报告的行为
4. 如果失败测试与报告的症状一致，即可确认 Bug

路径 B：基于浏览器的重现（UI、视觉、交互类 Bug）

使用 agent-browser CLI 进行浏览器自动化。不要使用任何替代的浏览器 MCP 集成或内置浏览器控制工具。有关设置和 CLI 用法详情，请参阅 agent-browser skill。

确认服务正在运行

agent-browser open http://localhost:${PORT:-3000}
agent-browser snapshot -i

如果服务未运行，请让用户启动开发服务并提供正确的端口。

要检测正确的端口，先检查项目指令文件（AGENTS.md、CLAUDE.md）中的端口引用，然后检查 package.json 中的 dev 脚本，再检查 .env 文件；如果仍未找到，则使用 3000。

按照重现步骤操作

导航到受影响的区域，并执行问题中提供的步骤：

agent-browser open "http://localhost:${PORT}/[affected_route]"
agent-browser snapshot -i

使用 agent-browser 命令与页面交互：

• agent-browser click @ref —— 点击元素
• agent-browser fill @ref "text" —— 填写表单字段
• agent-browser snapshot -i —— 捕获当前状态
• agent-browser screenshot bug-evidence.png —— 保存视觉证据

捕获 Bug 状态

复现 Bug 时：

1. 截取错误状态的屏幕截图
2. 检查控制台错误：查看浏览器输出和任何可见的错误消息
3. 记录触发问题的确切步骤顺序

路径 C：手动 / 特定环境复现

对于需要特定数据条件、用户角色、外部服务状态或无法自动化的 Bug：

1. 记录所需条件
2. 使用平台的提问工具询问用户（例如，Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user，或者提供选项并等待回复），询问他们是否能设置所需条件
3. 如有需要，引导他们手动执行复现步骤

如果复现失败

如果尝试最有可能的假设后仍无法复现 Bug：

1. 重新检查其余假设
2. 检查 Bug 是否与环境相关（版本、操作系统、浏览器、数据依赖）
3. 搜索代码库中受影响区域的近期变更：git log --oneline -20 -- [affected_files]
4. 记录尝试过的方法以及可能缺失的条件

阶段 4：调查

利用项目提供的可观测性工具，深入查找根本原因。

检查日志和跟踪记录

搜索复现时段附近的错误、警告或异常行为。具体检查内容取决于 Bug 以及项目提供的资源：

• 应用程序日志——使用原生内容搜索工具，在本地日志输出（开发服务器标准输出、日志文件）中搜索错误模式、堆栈跟踪或警告
• 错误跟踪——在项目的错误跟踪工具（Sentry、AppSignal、Bugsnag、Datadog 等）中检查相关异常
• 浏览器控制台——对于 UI Bug，检查开发者控制台输出中的 JavaScript 错误、失败的网络请求或 CORS 问题
• 数据库状态——如果 Bug 涉及数据，检查相关记录是否存在异常值、缺失的关联或约束冲突
• 请求 / 响应周期——检查服务器日志中的特定请求：状态码、参数、耗时、中间件行为

跟踪代码路径

从阶段 2 中确定的入口点开始，跟踪执行路径：

1. 使用原生文件读取工具阅读相关源文件
2. 找出行为偏离预期的位置
3. 检查边界情况：nil / null 值、空集合、边界条件、竞态条件
4. 查找可能引入 Bug 的近期变更：git log --oneline -10 -- [file]

阶段 5：记录调查结果

总结调查过程中发现的所有内容。

整理报告

将调查结果整理为：

1. 根本原因——具体问题及其所在位置（包含文件路径和行号，例如 app/services/example_service.rb:42）
2. 复现步骤——已验证的触发 Bug 步骤（标明已确认或未确认）
3. 证据——屏幕截图、测试输出、日志摘录、控制台错误
4. 建议的修复方案——如果修复方案明确，描述所需的具体代码变更
5. 待解决问题——仍不清楚或需要进一步调查的事项

采取任何外部操作前先向用户说明

向用户展示完整报告。未经明确确认，不要在 GitHub Issue 中发表评论，也不要采取任何外部操作。

使用平台的提问工具询问用户，或提供选项并等待回复：

Investigation complete. How to proceed?

1. Post findings to the issue as a comment
2. Start working on a fix
3. Just review the findings (no external action)

如果用户选择在 Issue 中发表评论：

gh issue comment $ARGUMENTS --body "$(cat <<'EOF'
## Bug Investigation

**Root Cause:** [summary]

**Reproduction Steps (verified):**
1. [step]
2. [step]

**Relevant Code:** [file:line references]

**Suggested Fix:** [description if applicable]
EOF
)"