mcpField
D
debugging-strategies

debugging-strategies

github.com/wshobson开发41.9k13.6k 次安装2 周前更新
代码仓库

关于 debugging-strategies

面向开发者的系统化调试指南，介绍复现、收集信息、提出假设和验证等步骤，适用于缺陷、性能及生产问题排查。

主要功能

  1. 01按科学方法推进排查
  2. 02复现并缩小问题范围
  3. 03收集错误与环境信息
  4. 04通过假设和实验验证原因
  5. 05按间歇性、性能等问题类型选择策略

适用场景

  1. 01追查难以稳定复现的缺陷
  2. 02调查应用性能问题
  3. 03分析生产环境故障
  4. 04理解陌生代码库中的问题

安装

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

$npx skills add https://github.com/wshobson/agents --skill debugging-strategies

安装后在 Claude Code 中输入/debugging-strategies确认已加载。

附带文件references/tools-and-techniques.md

详细介绍

调试策略

借助经过验证的策略、强大的工具和系统的方法，将调试从令人沮丧的猜测转变为系统化的问题解决过程。

适用场景

  • 排查难以捉摸的 bug
  • 调查性能问题
  • 理解不熟悉的代码库
  • 调试生产环境问题
  • 分析崩溃转储和堆栈跟踪
  • 分析应用程序性能
  • 调查内存泄漏
  • 调试分布式系统

核心原则

1. 科学方法

1. 观察：实际行为是什么？ 2. 提出假设：可能是什么原因导致的？ 3. 实验：验证你的假设 4. 分析：实验结果证实还是推翻了你的推断？ 5. 重复：直到找到根本原因

2. 调试心态

不要想当然：

  • “这不可能是 X”——确实有可能
  • “我没改过 Y”——还是检查一下
  • “在我的机器上能运行”——弄清楚原因

要做到：

  • 稳定复现问题
  • 隔离问题
  • 详细记录
  • 质疑一切
  • 卡住时休息一下
3. 橡皮鸭调试法

大声解释你的代码和问题（可以讲给橡皮鸭、同事或自己听）。这样往往能揭示问题所在。

系统化调试流程

阶段 1：复现
## Reproduction Checklist

1. **Can you reproduce it?**
   - Always? Sometimes? Randomly?
   - Specific conditions needed?
   - Can others reproduce it?

2. **Create minimal reproduction**
   - Simplify to smallest example
   - Remove unrelated code
   - Isolate the problem

3. **Document steps**
   - Write down exact steps
   - Note environment details
   - Capture error messages
阶段 2：收集信息
## Information Collection

1. **Error Messages**
   - Full stack trace
   - Error codes
   - Console/log output

2. **Environment**
   - OS version
   - Language/runtime version
   - Dependencies versions
   - Environment variables

3. **Recent Changes**
   - Git history
   - Deployment timeline
   - Configuration changes

4. **Scope**
   - Affects all users or specific ones?
   - All browsers or specific ones?
   - Production only or also dev?
阶段 3：提出假设
## Hypothesis Formation

Based on gathered info, ask:

1. **What changed?**
   - Recent code changes
   - Dependency updates
   - Infrastructure changes

2. **What's different?**
   - Working vs broken environment
   - Working vs broken user
   - Before vs after

3. **Where could this fail?**
   - Input validation
   - Business logic
   - Data layer
   - External services
阶段 4：测试并验证
## Testing Strategies

1. **Binary Search**
   - Comment out half the code
   - Narrow down problematic section
   - Repeat until found

2. **Add Logging**
   - Strategic console.log/print
   - Track variable values
   - Trace execution flow

3. **Isolate Components**
   - Test each piece separately
   - Mock dependencies
   - Remove complexity

4. **Compare Working vs Broken**
   - Diff configurations
   - Diff environments
   - Diff data

在选择调试工具或执行二分、差异、跟踪或内存分析之前，请先阅读 references/tools-and-techniques.md。

针对不同问题类型的调试模式

模式 1：间歇性 bug
## Strategies for Flaky Bugs

1. **Add extensive logging**
   - Log timing information
   - Log all state transitions
   - Log external interactions

2. **Look for race conditions**
   - Concurrent access to shared state
   - Async operations completing out of order
   - Missing synchronization

3. **Check timing dependencies**
   - setTimeout/setInterval
   - Promise resolution order
   - Animation frame timing

4. **Stress test**
   - Run many times
   - Vary timing
   - Simulate load
模式 2：性能问题
## Performance Debugging

1. **Profile first**
   - Don't optimize blindly
   - Measure before and after
   - Find bottlenecks

2. **Common culprits**
   - N+1 queries
   - Unnecessary re-renders
   - Large data processing
   - Synchronous I/O

3. **Tools**
   - Browser DevTools Performance tab
   - Lighthouse
   - Python: cProfile, line_profiler
   - Node: clinic.js, 0x
模式 3：生产环境 bug
## Production Debugging

1. **Gather evidence**
   - Error tracking (Sentry, Bugsnag)
   - Application logs
   - User reports
   - Metrics/monitoring

2. **Reproduce locally**
   - Use production data (anonymized)
   - Match environment
   - Follow exact steps

3. **Safe investigation**
   - Don't change production
   - Use feature flags
   - Add monitoring/logging
   - Test fixes in staging

最佳实践

  1. 先复现：无法复现，就无法修复
  2. 隔离问题：逐步移除复杂因素，直到得到最小用例
  3. 阅读错误信息：它们通常很有帮助
  4. 检查近期变更：大多数 bug 都是最近引入的
  5. 使用版本控制：Git 二分、追责和历史记录
  6. 适当休息：换个角度更容易看清问题
  7. 记录发现：帮助未来的自己
  8. 修复根本原因：不要只处理症状

常见调试错误

  • 同时做多项更改：一次只改一项
  • 不阅读错误信息：读完整个堆栈跟踪
  • 认为问题很复杂：问题往往很简单
  • 在生产环境中使用调试日志：发布前移除
  • 不使用调试器：console.log 并非总是最佳选择
  • 过早放弃：坚持就会有收获
  • 不测试修复结果：确认问题确实已解决

快速调试检查清单

## When Stuck, Check:

- [ ] Spelling errors (typos in variable names)
- [ ] Case sensitivity (fileName vs filename)
- [ ] Null/undefined values
- [ ] Array index off-by-one
- [ ] Async timing (race conditions)
- [ ] Scope issues (closure, hoisting)
- [ ] Type mismatches
- [ ] Missing dependencies
- [ ] Environment variables
- [ ] File paths (absolute vs relative)
- [ ] Cache issues (clear cache)
- [ ] Stale data (refresh database)

评论

支持 Markdown