debugging

调试

当任务是将一个具体故障转化为范围明确的诊断循环时，请使用此技能。

此技能的核心简单且可重复：

1. 用可测试的方式定义故障行为，
2. 构建或确认成本最低且可靠的复现方式，
3. 隔离范围最小的故障边界，
4. 针对每个假设执行一项有区分度的检查，
5. 在相同条件下验证修复。

在处理可能属于 log-analysis、testing-strategies、code-review 或 performance-optimization 的工作前，请先阅读 references/handoff-boundaries.md。 阅读 references/debug-loop.md，了解完整的实验循环框架。 如果问题显然属于回归、偶发故障、环境／配置不匹配或基于产物的调查，请阅读 references/mode-selection-and-fast-checks.md。

何时使用此技能

• 命令、测试、请求或 UI 流程失败，用户需要根因分析工作流
• Bug 可复现或接近可复现，需要在修复前缩小范围
• 回归可能存在明确的变更时间范围或最后一个已知正常状态
• 偶发故障需要通过重复运行获取证据、进行隔离，并稳定复现某个具体案例
• CI／staging／prod 专属行为已有足够证据，可用于比较环境或配置差异
• 用户询问如何复现、隔离、二分定位、确认或验证 Bug 修复

何时不使用此技能

• 用户只有日志／堆栈跟踪，仍需找到第一个可采取行动的故障 → 使用 log-analysis
• 实际任务是测试方案设计、偶发故障策略或覆盖率规划 → 使用 testing-strategies
• 任务是审查 diff／PR 的正确性、风险或证据是否缺失 → 使用 code-review
• 主要工作是遥测部署、仪表板或可观测性平台设计 → 使用 monitoring-observability
• 主要工作是测量瓶颈并权衡优化方案 → 使用 performance-optimization

指令

步骤 1：明确故障定义

以可重新测试的形式描述故障。

记录：

• 预期行为
• 实际行为
• 确切的触发条件、输入或状态
• 环境：本地／CI／staging／production／浏览器／移动端／运行时
• 确定性故障、偶发故障还是未知
• 如果可能是回归，记录最后一个已知正常状态

最低限度的格式：

Expected: ...
Actual: ...
Trigger: ...
Environment: ...
Confidence: high | medium | low

如果报告仍只是“出了点问题”，只有大量日志而没有缩小后的症状，请先转交给 log-analysis。

步骤 2：选择合适的首个证据来源

选择成本最低且能证伪或确认下一个假设的路径。

使用以下快速判断：

• 已知会失败的命令／测试／请求／UI 流程 → 直接复现
• 有最后一个已知正常状态的回归 → 比较近期变更，并考虑使用 git bisect
• 偶发／间歇性故障 → 先通过重复运行测量发生频率
• 仅在 CI／staging／prod 出现 → 先比较环境／配置／运行时信息，再推测代码原因
• 基于产物的案例 → 检查第一份有意义的日志／跟踪记录／屏幕截图，然后将范围缩小到一个可疑边界
• 仅与性能有关的投诉 → 转交给 performance-optimization，除非仍需诊断某个具体的异常行为

步骤 3：构建最小且可靠的复现方式

优先选择成本最低但仍能触发故障的复现方式。

常见形式：

• 一条 CLI 命令
• 一个 HTTP 请求或 API 调用
• 一个包含准确步骤的 UI 流程
• 一个失败的测试或 fixture
• 一组存档文件／种子／载荷／配置组合
• 一个用于排查回归的提交范围

实用技巧：

• 减少无关的准备工作
• 尽可能固定时间／随机性／网络条件
• 记录存在差异的确切环境／配置值
• 让重复运行循环聚焦于一个可疑因素

步骤 4：提出修复方案前，先隔离问题边界

先缩小问题范围。

隔离角度：

1. 边界 — UI、API、DB、worker、配置、依赖项或资源/运行时
2. 输入 — 一个负载、记录、种子、场景或测试夹具
3. 历史 — 正常与异常之间发生了什么变化
4. 环境 — 本地、CI、预发布环境或生产环境
5. 时序 — 顺序、重试、缓存、时钟、异步等待、共享状态

高价值问题：

• 能否指出一个文件/模块/配置分支，作为当前首要嫌疑对象？
• 故障涉及数据形状、状态转换、配置漂移、依赖项行为，还是代码路径？
• 当前瓶颈仍是诊断，还是任务已转向审查、测试策略或优化工作？

步骤 5：针对每个假设，运行一项有区分力的检查

不要一次性修改五处。

对于每个假设：

• 说明它为何能解释故障
• 先运行一项只读或可撤销的检查
• 记录结果
• 根据证据保留或排除该假设

适合作为首轮检查的操作：

• 检查已缩小范围的边界处的请求/负载/配置
• 对比一个正常状态和一个异常状态
• 重新运行一项有针对性的测试，而非整个测试套件
• 对嫌疑提交范围执行 diff
• 仅在已缩小范围的边界处添加临时检测代码

步骤 6：使用合适的模式流程

明确问题类型后，按照 references/mode-selection-and-fast-checks.md 中匹配的流程操作：

• 回归问题调试
• 间歇性故障调试
• 环境/配置不匹配调试
• 对日志/跟踪/截图进行分流后，基于产物开展调试
• 运行时 / 浏览器 / 游戏循环调试

步骤 7：修复根因，然后验证

好的调试结果应证明问题根因已得到处理，而不只是掩盖了症状。

验证清单：

• 复现问题的步骤现在能够通过
• 邻近的边界情况仍然表现正确
• 在可行时，有防止回归的保护措施
• 解释与观察到的故障相符
• 修复范围小于最初的排查范围

步骤 8：证据仍不足时，如实升级处理

如果仍无法复现或隔离问题：

1. 说明当前置信度较低，
2. 只索取最少的缺失材料，
3. 不要假装已知根因，
4. 优先再做一项有区分力的检查，而非推测性修改。

输出格式

始终返回简洁的调试简报或调试计划。

# Debugging Brief

## Failure definition
- Expected: ...
- Actual: ...
- Reproducer: ...
- Confidence: high | medium | low

## Isolation result
- Narrowed boundary: ...
- Recent change / env difference / artifact clue: ...

## Hypotheses and checks
1. Hypothesis: ...
   - Check: ...
   - Result: ...

## Likely root cause
- 1-3 sentences grounded in evidence

## Fix direction
1. ...
2. ...

## Verification
- Reproducer rerun: ...
- Regression guard: ...

## Handoff
- Stay in `debugging` | route to `diagnosing-bugs` (hard/flaky bug needing a HITL feedback loop) | route to `log-analysis` | route to `testing-strategies` | route to `code-review` | route to `performance-optimization`

示例

示例 1：重构后出现回归

输入

保存个人资料时，如果没有上传新头像，现有头像现在会被清除。重构前不会这样。

输出示意

• 用一次可复现的表单提交，明确预期行为与实际行为
• 对比重构前后的更新路径
• 检查缺失字段和显式 null 是否被视为相同
• 通过有针对性的回归测试进行验证，并重新运行原始流程

示例 2：CI 间歇性故障

输入

这个结账测试在本地能通过，但在 CI 中大约每八次就会失败一次。

输出示意

• 将此情况标记为间歇性故障，而非确定性故障
• 循环重复运行，并对比时序/共享状态/环境差异
• 先只检查失败的测试及其附近的测试夹具
• 只有当任务扩大到整个测试套件的间歇性故障策略时，才转交给 testing-strategies

示例 3：仅生产环境中出现的问题，并有产物线索

输入

这个任务只在预发布环境中失败。我有首次失败请求的负载和配置差异。

输出示意

• 将此问题作为环境/配置不匹配问题进行调试
• 修改代码前，先对比预发布环境与本地/运行时的实际情况
• 缩小范围，找出导致行为变化的那个标志/版本/密钥分支
• 在修正后的配置下，使用相同负载进行验证

示例 4：只有症状的日志转储

输入

这里有 500 行重试记录和堆栈跟踪。你能调试一下吗？

输出示意

• 首先转交给 log-analysis
• 说明仍需缩小范围，才能找到第一个可采取行动的故障
• 不要假装现在就能开始根因排查流程

最佳实践

1. 修复前先复现——未经验证的修复只是猜测。
2. 先采用成本最低的证据来源——直接复现、重复运行、环境差异或产物线索。
3. 明确选择模式——回归、偶发失败、环境/配置、基于产物和运行时问题，需要采用不同的首要检查方式。
4. 将症状排查与诊断分开——日志有助于开始排查，但无法完成诊断。
5. 一次只改一处——调试是一个实验循环。
6. 最后进行验证——每项结果都应说明如何确认原因。

参考资料

• Visual Studio Code：调试
• Playwright：调试测试
• GitHub 文档：启用调试日志
• Git：git-bisect 文档
• Google Testing Blog：Google 的不稳定测试及其缓解方法