复现 → 定位根源 → 一次性修复
目标不是「让报错消失」,而是找到产生问题的那个地方,改一次,之后不再复发。 任何一步没有证据就进入下一步,视为失败。
0. 先问清楚(不清楚时必须追问)
用户描述往往只给了「症状」。动手前最少确认:
- 环境:哪台机器 / 哪个平台(mac / Windows / 线上 ECS)?哪个版本或提交?
- 路径:具体点了什么、跑了哪个脚本/命令、从哪一步开始?
- 条件:什么时候必现、什么时候不现?数据/账号/权限有什么特殊?
- 预期 vs 实际:期望发生什么,实际发生了什么(原话 + 截图/日志/退出码)?
- 可复现性:能再演一次吗?上次成功是什么时候?
规则:
- 一次只问会改变工作方向的问题(用 AskUserQuestion,给选项 + 推荐项);不因细节小事阻塞。
- 区分用户观察与我们的推断,推断必须标成假设并去验证。
- 用户给的截图/日志是事实,但「截的是哪个环境」必须确认(曾把安装版当源码模式排查)。
1. 复现:必须是真机、真实场景
- 优先在用户真实环境复现:真机、真实数据、真实账号、真实网络。模拟结果只能作为线索, 不能当作「已复现」;无法真机复现时如实说明边界。
- 建最小复现探针:
- 最小输入(一个请求、一张卡片、一段文本);
- 最小代码路径(只走到出问题的那一层);
- 明确的观测点(日志、返回值、DOM/AX 快照、字节数、哈希)。
- 探针原则:一次只改一个变量;可回退;临时验证脚本不要进仓库测试,用完即删。
- 记录复现证据:命令、版本/提交、原始输出、截图。没有证据的「复现了」不算数。
2. 第一性原理定位(从事实出发,逐层排除)
从「这个系统必须满足什么」出发,而不是从「可能是哪个 bug」出发:
- 画出真实链路:输入 → 路由/解析 → 判定 → 执行 → 输出。
- 每一层给出可观测证据(日志、状态码、数据快照),逐层排除。
- 找到后问一句:同一个问题的答案出现在几个地方?
- 答案 > 1 处 = 漂移源(同一语义有两份判定/两份配置),这才是根因常见形态。
- 区分症状与根因:症状是用户看到的;根因是「改掉它,症状必然不再出现」的那一处。
- 追溯「为什么以前没有、现在有了」:哪次改动/配置/数据变化让路径变了。
3. 验证根因(可证伪,而不是看起来像)
- 提出预测:如果根因是 X,那么做 Y 应该出现 Z;做对照实验验证。
- 常用对照:开/关开关、回滚一个提交、把输入缩到最小、替换单一依赖。
- 相关性不算因果:两个现象同时出现不等于一个是另一个的原因。
- 权限/环境类问题,必须在与用户相同的身份与层验证(源码模式 ≠ 安装版;普通用户 ≠ root)。
- 若实验否定了假设,丢掉假设重新来,不要修补旧结论。
4. 修复:奥卡姆剃刀
- 只改产生问题的那一处。能删的不加;能被现有机制表达的不新增概念。
- 不为不存在的问题加防御:先证明问题真实存在(复现路径/数据/日志),再写代码; 调研后暴露面极小甚至没有,就如实说「不需要改」。
- 同一业务语义只保留一处判定/配置/策略;发现两份就收敛,再改。
- 不夹带重构、不夹带行为变更:回归时才能判断是哪一边出的事。
- 回归用同一个探针:改前红、改后绿;再补一条能钉住根因的最小守卫测试(不做过度工程)。
- 注释只写「为什么」:隐藏约束、反直觉决策、踩过的坑。
5. 收口(交付模板)
按这个结构汇报,缺一项就说明缺哪项:
- 现象:用户看到什么(原话/截图)。
- 复现条件:环境、版本、路径、前提;是否真机复现(没复现就直说)。
- 证据:命令与原始输出、探针结果、对照实验。
- 根因:一句话说清「哪一处、为什么」;附上「同一个答案出现在几处」的结论。
- 修复:改了哪里、为什么这是最小改动、没改什么以及为什么不需要。
- 验证:改前/改后探针对比 + 新增守卫测试。
- 未覆盖边界:没验证的环境/数据/路径,以及风险。
反模式(出现即停)
- 没复现就开始改;把「猜到的原因」当根因。
- 靠加 try/except、加超时、加兜底让报错消失。
- 为了让测试变绿去改测试,而不是改实现(除非测试本身断言错了,且能给理由)。
- 同时在多处打补丁——那说明根因还没找到。
- 用模拟环境的结果冒充真机结论。
