mcpField
S
shared-bug-investigation

shared-bug-investigation

github.com/desquared开发456 次安装4 周前更新
代码仓库

关于 shared-bug-investigation

面向开发者的系统化 Bug 调查技能，以科学方法从可复现的问题出发，定位根因并验证修复及回归测试。

主要功能

  1. 01项目与环境信息收集
  2. 02复现问题并记录证据
  3. 03提出并排序可测试假设
  4. 04控制变量实验与根因分析
  5. 05验证修复并执行回归测试

适用场景

  1. 01调查间歇性或稳定复现的故障
  2. 02追查代码、状态或集成问题
  3. 03检查修复是否引入回归

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/desquared/agents-rules-skills --skill shared-bug-investigation

安装后在 Claude Code 中输入/shared-bug-investigation确认已加载。

附带文件references/debugging-techniques.mdreferences/quick-reference.md

详细介绍

Bug 调查——科学方法

运用科学方法系统地调查并解决软件 Bug。

科学方法流程

  1. 观察 - 收集问题相关数据
  2. 提出假设 - 形成可检验的解释（按可能性排序）
  3. 实验 - 通过受控变更检验假设
  4. 分析 - 客观解读结果
  5. 得出结论 - 找出根本原因并验证修复

核心原则

  • 先了解上下文 - 调查前先了解项目
  • 以假设为导向 - 形成可检验的假设之前，绝不贸然寻找解决方案
  • 隔离变量 - 一次只改变一项
  • 可靠复现 - 无法复现的问题就无法修复
  • 追根究底，不只处理症状 - 深入探究，不满足于表面修复
  • 严格验证 - 确认修复解决问题且没有引入回归

调查工作流

阶段 1：项目上下文（2-5 分钟）

调查前先了解：

  • 语言及版本（Python 3.11、Java 17、Go 1.21 等）
  • 构建系统（Gradle、npm、Cargo、Make 等）
  • 关键依赖和框架
  • 架构模式（MVC、微服务等）
  • 测试配置

快速了解：

# Find package managers
view package.json / requirements.txt / Cargo.toml / pom.xml

# Check config files  
view .env / config.yml / settings.py

# Identify entry points
view main.* / index.* / app.*

输出：一行上下文描述

Python 3.11, Flask API, PostgreSQL, pytest, Docker
阶段 2：问题定义

收集：

  • 错误消息（完整文本、代码）
  • 堆栈跟踪 / 日志
  • 复现步骤
  • 预期行为与实际行为
  • 环境（操作系统、版本、配置）
  • 可复现性（总是 / 有时 / 很少）

记录：

Bug: [Short description]
Reproduces: [Always/Sometimes/Unable]
Error: [Key error message]
Steps:
1. [Action 1]
2. [Action 2]
3. [Failure occurs]
Expected: [What should happen]
Actual: [What happens]
阶段 3：假设（按可能性排序）
阶段 3：假设（按可能性排序）

提出 2-4 个可检验的假设，并按可能性排序。

H1：[最可能的原因]

  • 支持证据：[此原因可能性较高的原因]
  • 测试：[如何证实或证伪]
  • 如果为真：[预期结果]
  • 如果为假：[预期结果]

H2：[其他可能的原因]

  • 支持证据：[支持性观察]
  • 测试：[可证伪的实验]

常见类别：

  • 逻辑错误（差一错误、运算符错误、条件不正确）
  • 状态问题（竞态条件、未初始化、数据过时）
  • 类型 / 数据问题（null/nil、类型不匹配、解析错误）
  • 并发问题（数据竞争、死锁、线程安全）
  • 集成问题（API 不匹配、版本不兼容）
  • 环境问题（配置、平台特定问题、资源限制）
阶段 4：实验

针对每个假设：

测试 H1：[假设名称]

  • 变更：[要修改的一个变量]
  • 测量：[要观察的内容]
  • 方法：[具体步骤]
  • 结果：[实际结果]
  • 结论：[已证实 / 已证伪]

技巧：

  • 在关键位置添加日志
  • 使用调试器断点
  • 二分搜索（移除一半代码）
  • 最小复现（精简至必要内容）
  • 对比正常与故障状态
  • 隔离组件
阶段 5：根本原因

已确认： [清楚说明实际原因]

证据： [从观察 → 假设 → 验证的证据链]

发生原因：

  • 直接原因：[技术原因]
  • 促成因素：[导致问题出现的因素]
  • 系统性原因：[如有，更深层的问题]
阶段 6：解决方案与验证

修复： [要进行的具体变更]

为何有效： [解释因果关系]

验证：

  1. 复现 Bug（确认失败）
  2. 应用修复
  3. 重新测试（确认成功）
  4. 测试边界情况
  5. 运行测试套件（确认没有回归）
  6. 为此 Bug 添加测试

预防：

  • [要添加的测试]
  • [要添加的断言]
  • [要避免的模式]

调查技巧

二分搜索： 移除一半代码，测试 Bug 是否仍然存在。针对故障部分重复此过程，直到定位问题。

最小复现： 精简至少于 50 行且能复现问题的代码，去除干扰。

差异测试： 对比正常与故障状态（提交、版本、配置）。

策略性日志： 在关键决策点添加输出，追踪执行流程。

橡皮鸭调试法： 大声逐行讲解代码，通常能发现逻辑错误。

常见错误模式（与语言无关）

逻辑错误：

  • 差一错误：i < n 与 i <= n
  • 运算符错误：&& 与 ||，== 与 =
  • 否定错误：!condition 的逻辑反转

状态问题：

  • 竞态条件：并发访问未进行同步
  • 未初始化：变量尚未赋值就被使用
  • 状态过期：使用过时的缓存数据

类型/数据：

  • 空值/nil 解引用
  • 类型强制转换错误
  • 整数溢出
  • 浮点精度

并发：

  • 死锁：相互等待锁
  • 数据竞争：未同步地访问共享数据
  • 线程安全：在多个线程上运行非线程安全代码

集成：

  • API 契约不匹配
  • 版本不兼容
  • 缺少依赖项
  • 配置错误

输出格式

# Bug Investigation: [Name]

## Context
[One-line: Language, framework, architecture]

## Problem
Error: [Message]
Reproduces: [Always/Sometimes]
Steps: [1,2,3]

## Hypotheses
H1: [Most likely] - Test by [method]
H2: [Alternative] - Test by [method]

## Investigation
Tested H1: [Result - validated/invalidated]
[If needed] Tested H2: [Result]

## Root Cause
[One sentence explanation]
Evidence: [What confirmed it]

## Solution
Fix: [Specific change]
Why it works: [Explanation]
Validated: [Tested successfully]

## Prevention
- Test added: [Description]
- Warning signs: [What to watch for]

快速决策树

症状 → 可能类别：

  • 间歇性故障 → 并发/状态
  • 总是以相同方式失败 → 逻辑错误
  • 空值/nil 崩溃 → 类型/数据
  • 仅在特定环境中出现 → 配置
  • 性能下降 → 资源/算法
  • 更新依赖项后出现 → 集成

重要提醒

  • 从发现上下文开始
  • 编码前先提出假设
  • 每次只更改一个变量
  • 修复前先复现问题
  • 严格验证修复
  • 添加回归测试
  • 记录根本原因

评论

支持 Markdown