// Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation). NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
| name | systematic-debugging |
| description | Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes - four-phase framework (root cause investigation, pattern analysis, hypothesis testing, implementation). NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. |
| metadata | {"short-description":"系统化调试与根因分析","keywords":["systematic-debugging","调试","Bug 修复","根因分析","问题诊断","堆栈追踪","生产环境调试","root cause","debugging"],"category":"调试","author":"Bensz Conan","platform":"Claude Code | OpenAI Codex | ChatGPT","iron-law":"NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST\n"} |
bensz-collect-bugs 规范记录到 ~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。gh 上传新增 bug 到 huangwb8/bensz-bugs；不要 pull / clone 整个仓库。NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
违反规则的信件就是违反规则的精神。
无例外：
| 借口 | 现实 |
|---|---|
| "快速修复现在，稍后调查" | 永不会有"稍后"。技术债积累 |
| "尝试改变 X，看是否有效" | 猜测不是调试。可能碰巧修复但未理解 |
| "添加多个更改，运行测试" | 无法确定哪个更改有效。浪费调试时间 |
| "可能大概差不多是 X" | 模糊理解导致错误修复 |
| "不完全理解但可能有效" | 理解不完全=修复不完整 |
所有这些意味着：停止修复。回到根因调查阶段。
任何修复前：
仔细阅读错误消息
一致复现
检查最近变更
多组件系统收集证据
# 对于每个组件边界：
- 记录进入组件的数据
- 记录退出组件的数据
- 验证环境/配置传播
- 检查每层状态
运行一次以收集显示何处中断的证据
然后分析证据以识别失败组件
然后调查该特定组件
追踪数据流
系统化调试 不是碰运气，而是方法化地解决问题的科学流程。
┌─────────────────────────────────────────────────────────┐
│ 收集证据 → 形成假设 → 系统验证 → 定位根因 → 实施修复 │
└─────────────────────────────────────────────────────────┘
核心原则：
在以下场景时激活：
信息收集清单：
| 证据类型 | 收集方法 | 重要性 |
|---|---|---|
| 完整堆栈追踪 | 复制完整错误信息 | ⭐⭐⭐⭐⭐ |
| 相关日志 | 查看应用日志 | ⭐⭐⭐⭐⭐ |
| 复现步骤 | 记录如何触发问题 | ⭐⭐⭐⭐ |
| 环境信息 | OS、版本、依赖 | ⭐⭐⭐ |
| 代码变更 | 最近的 Git 提交 | ⭐⭐⭐⭐ |
| 用户输入 | 触发问题的数据 | ⭐⭐⭐ |
堆栈追踪分析示例：
# 示例错误
Traceback (most recent call last):
File "app.py", line 45, in process_order
result = payment_service.charge(amount)
File "payment.py", line 78, in charge
return api_client.post("/charge", data)
File "api.py", line 23, in post
response = self.session.request(method, url, **kwargs)
ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
分析要点：
假设生成规则：
假设模板：
假设：[问题描述] 的原因是 [根本原因]
触发条件：[什么情况下会出现]
验证方法：[如何证明或否定]
假设示例：
假设：SSL 错误的原因是生产环境缺少证书文件
触发条件：部署到生产环境后首次调用 API
验证方法：检查 /etc/ssl/certs/ 目录是否存在证书
常见根因分类：
| 类别 | 典型原因 | 检查方法 |
|---|---|---|
| 配置问题 | 环境变量、配置文件错误 | 检查 .env、config |
| 依赖问题 | 版本冲突、缺失依赖 | 检查 requirements.txt |
| 数据问题 | 空值、格式错误、边界值 | 检查输入数据 |
| 并发问题 | 竞态条件、死锁 | 检查锁、线程安全 |
| 资源问题 | 内存泄漏、连接池耗尽 | 检查资源使用 |
| 逻辑错误 | 边界条件、空值处理 | 代码审查 |
验证原则：
验证方法：
# 方法 1：添加日志
def process_order(order_id):
logger.info(f"Processing order: {order_id}")
order = get_order(order_id)
logger.debug(f"Order data: {order}")
# ...
# 方法 2：断点调试
import pdb; pdb.set_trace()
# 方法 3：简化输入
def test():
# 用最小输入验证
process_order({"id": 1, "amount": 0})
验证记录模板：
## 假设验证记录
### 假设 1：证书文件缺失
- **验证方法**：检查文件是否存在
- **验证结果**：❌ 文件存在
- **结论**：假设不成立，排除
### 假设 2：证书过期
- **验证方法**：检查证书有效期
- **验证结果**：✅ 证书已于 3 天前过期
- **结论**：假设成立，定位根因
区分症状与根因：
使用五问法（5 Whys）深入挖掘：
问题：订单处理失败
Why 1: 为什么失败？
→ API 调用返回 500 错误
Why 2: 为什么 API 返回 500？
→ 数据库查询超时
Why 3: 为什么查询超时？
→ 缺少索引导致全表扫描
Why 4: 为什么缺少索引？
→ 新增字段时未同步添加索引
Why 5: 为什么未添加索引？
→ 没有 Code Review 流程
根因：缺少 Code Review 机制（而非"API 返回 500"）
根因特征：
修复原则：
修复清单：
## 修复计划
### 代码修复
- [ ] 修改代码：[具体位置]
- [ ] 添加测试：[测试用例]
- [ ] 运行测试确认通过
### 预防措施
- [ ] 添加检查机制
- [ ] 更新文档
- [ ] 团队分享经验
### 验证
- [ ] 本地验证
- [ ] 测试环境验证
- [ ] 生产环境验证
当问题可能出现在多个位置时：
# 在中间点添加日志
def complex_function(data):
logger.info("Step 1: Start")
result1 = step1(data)
logger.info(f"Step 1 result: {result1}")
logger.info("Step 2: Start")
result2 = step2(result1)
logger.info(f"Step 2 result: {result2}")
logger.info("Step 3: Start")
result3 = step3(result2)
logger.info(f"Step 3 result: {result3}")
return result3
# 从复杂场景中提取最小复现用例
def test_minimal_reproduction():
# 不需要完整的订单数据
order = {"amount": 100} # 最小输入
result = process_payment(order)
assert result.success
# 对比工作版本和失败版本
def test_working_vs_broken():
# 工作版本
result_working = old_api_call(data)
# 失败版本
try:
result_broken = new_api_call(data)
except Exception as e:
print(f"Broken: {e}")
# 对比差异
compare_results(result_working, result_broken)
# 使用 Docker 隔离环境
docker run -it python:3.11 bash
# 或使用虚拟环境
python -m venv debug_env
source debug_env/bin/activate
症状：间歇性失败，时好时坏
根因：竞态条件、异步操作未正确等待
调试方法：
# 添加重试和延迟
from tenacity import retry, stop_after_attempt, wait_fixed
@retry(stop=stop_after_attempt(3), wait=wait_fixed(1))
def flaky_operation():
# 可能失败的操作
pass
症状：性能逐渐下降，最终崩溃
根因：内存泄漏
调试方法：
import tracemalloc
tracemalloc.start()
# ... 运行代码 ...
snapshot = tracemalloc.take_snapshot()
top_stats = snapshot.statistics('lineno')
for stat in top_stats[:10]:
print(stat)
症状：测试单独通过，批量运行失败
根因：测试间共享状态
调试方法：
@pytest.fixture(autouse=True)
def reset_state():
# 每个测试前重置状态
reset_database()
reset_cache()
yield
cleanup()
修复完成后，检查：
当用户明确要求"初始化项目"、"创建项目指令文件"或"生成 AGENTS.md"时使用。完全自动化：自动检测操作系统默认语言，分析项目目录结构（支持 Python/Web/Rust/Go/Java/数据科学/文档项目等），推断项目类型和用途，一键生成规范的项目指令文档。生成结果包括：AGENTS.md（跨平台通用项目指令，Single Source of Truth）、CLAUDE.md（Claude Code 特定适配，通过 @./AGENTS.md 引用）、README.md（项目介绍与使用方法）、CHANGELOG.md（项目变更记录）、.gitignore（Git 忽略规则，安全优先），并在完整初始化时自动补齐 `docs/` 与 `docs/plans/`。
当需要把本仓库 pipelines/skills 下的所有 skills 安装到系统级（默认同时安装到 Codex: ~/.codex/skills 和 Claude Code: ~/.claude/skills），以便在任意项目/对话中可被发现与调用时使用。使用 MD5 哈希进行版本控制，仅安装有更新的 skills；支持 --skill 指定单个或少量技能安装/更新、强制覆盖安装、指定单一目标安装和远程安装模式（--remote --check/--auto）。
当用户明确要求"测试代码"、"运行代码审查"或"进行代码自检"时使用。通过多轮 A 轮批判性代码审查 + B 轮代码质量原则检查，系统化发现、记录、修复程序代码中的问题，并将计划/过程/结果统一沉淀到目标代码根目录的 `tmp/run_{timestamp}/tests/` 隔离工作区。⚠️ 不适用：用户只是想优化功能（应直接修改）、只是询问代码问题（应直接回答）、没有明确"测试代码"意图。
当用户明确要求"使用 awesome-code / 多代理协作 / 并行协调开发"时使用。通过脚本收集可用 Agent 摘要、配置约束与 `dispatch_gate`，再由 AI 自主判断 single-pass / focused-agent / parallel / sequential 策略并选择子代理；当配置中的 required route agent 缺失时必须阻塞继续执行。⚠️ 不适用：用户仅需单一角色的简单修改或咨询、用户未明确表达多代理协作意图、用户只是了解技能概念。
Use when completing tasks, implementing major features, or before merging to verify work meets requirements - reviews implementation against plan or requirements with severity分级（Critical/Important/Minor）. NO MERGE WITHOUT CODE REVIEW FIRST.
Use when you have a spec or requirements for a multi-step task, before touching code