# Repro And Root Cause

> 复现问题并验证根源，追求一次性解决：先问清真实场景，用最小探针在真机/真实数据上复现，第一性原理逐层定位，奥卡姆剃刀只改产生问题的那一处，改后同一探针复测。用户报 bug、说「复现」「根因」「为什么」「grill me」或要求排查线上问题时适用。

- Skill: `aaaaqwq/repro-and-root-cause` (Agent Skill)
- Install (CLI): `npx get-skill add aaaaqwq/repro-and-root-cause`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aaaaqwq/repro-and-root-cause/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aAAaqwq (https://skillmd.com/u/aaaaqwq)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/aaaaqwq/repro-and-root-cause

---


# 复现 → 定位根源 → 一次性修复

目标不是「让报错消失」，而是**找到产生问题的那个地方，改一次，之后不再复发**。
任何一步没有证据就进入下一步，视为失败。

## 0. 先问清楚（不清楚时必须追问）

用户描述往往只给了「症状」。动手前最少确认：

- **环境**：哪台机器 / 哪个平台（mac / Windows / 线上 ECS）？哪个版本或提交？
- **路径**：具体点了什么、跑了哪个脚本/命令、从哪一步开始？
- **条件**：什么时候必现、什么时候不现？数据/账号/权限有什么特殊？
- **预期 vs 实际**：期望发生什么，实际发生了什么（原话 + 截图/日志/退出码）？
- **可复现性**：能再演一次吗？上次成功是什么时候？

规则：
- 一次只问会**改变工作方向**的问题（用 AskUserQuestion，给选项 + 推荐项）；不因细节小事阻塞。
- 区分**用户观察**与**我们的推断**，推断必须标成假设并去验证。
- 用户给的截图/日志是事实，但「截的是哪个环境」必须确认（曾把安装版当源码模式排查）。

## 1. 复现：必须是真机、真实场景

- 优先在**用户真实环境**复现：真机、真实数据、真实账号、真实网络。模拟结果只能作为线索，
  不能当作「已复现」；无法真机复现时**如实说明边界**。
- 建**最小复现探针**：
  - 最小输入（一个请求、一张卡片、一段文本）；
  - 最小代码路径（只走到出问题的那一层）；
  - 明确的观测点（日志、返回值、DOM/AX 快照、字节数、哈希）。
- 探针原则：一次只改一个变量；可回退；**临时验证脚本不要进仓库测试**，用完即删。
- 记录复现证据：命令、版本/提交、原始输出、截图。**没有证据的「复现了」不算数。**

## 2. 第一性原理定位（从事实出发，逐层排除）

从「这个系统必须满足什么」出发，而不是从「可能是哪个 bug」出发：

1. 画出真实链路：输入 → 路由/解析 → 判定 → 执行 → 输出。
2. 每一层给出**可观测证据**（日志、状态码、数据快照），逐层排除。
3. 找到后问一句：**同一个问题的答案出现在几个地方？**
   - 答案 > 1 处 = 漂移源（同一语义有两份判定/两份配置），这才是根因常见形态。
4. 区分**症状**与**根因**：症状是用户看到的；根因是「改掉它，症状必然不再出现」的那一处。
5. 追溯「为什么以前没有、现在有了」：哪次改动/配置/数据变化让路径变了。

## 3. 验证根因（可证伪，而不是看起来像）

- 提出预测：**如果根因是 X，那么做 Y 应该出现 Z**；做对照实验验证。
- 常用对照：开/关开关、回滚一个提交、把输入缩到最小、替换单一依赖。
- 相关性不算因果：两个现象同时出现不等于一个是另一个的原因。
- 权限/环境类问题，必须在**与用户相同的身份与层**验证（源码模式 ≠ 安装版；普通用户 ≠ root）。
- 若实验否定了假设，**丢掉假设重新来**，不要修补旧结论。

## 4. 修复：奥卡姆剃刀

- **只改产生问题的那一处**。能删的不加；能被现有机制表达的不新增概念。
- 不为不存在的问题加防御：先证明问题真实存在（复现路径/数据/日志），再写代码；
  调研后暴露面极小甚至没有，就如实说「不需要改」。
- 同一业务语义只保留**一处**判定/配置/策略；发现两份就收敛，再改。
- 不夹带重构、不夹带行为变更：回归时才能判断是哪一边出的事。
- 回归用**同一个探针**：改前红、改后绿；再补一条能钉住根因的最小守卫测试（不做过度工程）。
- 注释只写「为什么」：隐藏约束、反直觉决策、踩过的坑。

## 5. 收口（交付模板）

按这个结构汇报，缺一项就说明缺哪项：

- **现象**：用户看到什么（原话/截图）。
- **复现条件**：环境、版本、路径、前提；是否真机复现（没复现就直说）。
- **证据**：命令与原始输出、探针结果、对照实验。
- **根因**：一句话说清「哪一处、为什么」；附上「同一个答案出现在几处」的结论。
- **修复**：改了哪里、为什么这是最小改动、没改什么以及为什么不需要。
- **验证**：改前/改后探针对比 + 新增守卫测试。
- **未覆盖边界**：没验证的环境/数据/路径，以及风险。

## 反模式（出现即停）

- 没复现就开始改；把「猜到的原因」当根因。
- 靠加 try/except、加超时、加兜底让报错消失。
- 为了让测试变绿去改测试，而不是改实现（除非测试本身断言错了，且能给理由）。
- 同时在多处打补丁——那说明根因还没找到。
- 用模拟环境的结果冒充真机结论。

