/debug

name: debug
description: "Systematic debugging methods, log analysis, and performance diagnostics. Use when debugging issues, analyzing errors, or troubleshooting incidents."
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
parent: quality

调试技能

本技能提供系统化的调试方法和技巧。

触发条件

• 调试代码问题
• 分析错误日志
• 调查性能问题
• 排查生产事故
• 修复 Bug

调试原则

黄金法则

1. **复现问题** - 先能稳定复现，再开始调试 2. **最小化** - 找到最小可复现用例 3. **二分法** - 缩小问题范围 4. **假设验证** - 提出假设，验证假设 5. **记录过程** - 记录尝试过的方法

调试流程

问题描述 → 复现问题 → 缩小范围 → 定位原因 → 修复验证 → 记录总结

问题描述模板

记录时包含以下要素:

| 要素 | 内容 | | ------------ | ------------------------ | | 问题描述 | 简要描述问题现象 | | 预期 vs 实际 | 期望行为与实际行为的差异 | | 复现步骤 | 可稳定复现的最小步骤 | | 环境信息 | OS、语言版本、依赖版本 | | 错误信息 | 完整的错误堆栈或日志 | | 已尝试方案 | 每个方案及其结果 |

日志调试

有效的日志输出

// ❌ 无用的日志
console.log("here");
console.log(data);

// ✅ 有信息量的日志
console.log("[UserService.createUser] 开始创建用户:", {
  email: user.email,
  timestamp: new Date().toISOString(),
});

console.log("[UserService.createUser] 数据库插入成功:", {
  userId: result.id,
  duration: Date.now() - startTime,
});

console.error("[UserService.createUser] 创建失败:", {
  error: error.message,
  stack: error.stack,
  input: { email: user.email },
});

# ❌ 无用的日志
print("here")
print(data)

# ✅ 有信息量的日志
import logging
logger = logging.getLogger(__name__)

logger.info(f"[create_user] 开始创建用户: email={email}")
logger.info(f"[create_user] 创建成功: user_id={user.id}, duration={duration}ms")
logger.error(f"[create_user] 创建失败: error={str(e)}", exc_info=True)

日志级别使用

| 级别 | 用途 | 示例 | | ----- | -------------- | ------------------ | | DEBUG | 详细调试信息 | 函数参数、中间状态 | | INFO | 正常操作信息 | 用户登录、订单创建 | | WARN | 警告但可继续 | 配置缺失使用默认值 | | ERROR | 错误但可恢复 | API 调用失败重试 | | FATAL | 致命错误需退出 | 数据库连接失败 |

断点调试

VS Code 调试配置 (`.vscode/launch.json`)

| 场景 | type | 关键配置 | | --------- | -------- | ------------------------------------------ | | Node.js | `node` | `program`, `preLaunchTask`, `outFiles` | | Python | `python` | `program: "${file}"`, `integratedTerminal` | | Jest 测试 | `node` | `program: jest`, `args: ["--runInBand"]` |

条件断点

在循环中设置条件表达式 (如 `item.id === 'target-id'`)，仅在满足条件时暂停。

网络与数据库调试

> 详见 [network-debug.md](network-debug.md)

• **网络调试**: Axios 拦截器日志、cURL 调试技巧
• **数据库调试**: Prisma/SQLAlchemy 查询日志、慢查询分析 (EXPLAIN ANALYZE)

性能调试

> 详见 [performance-debug.md](performance-debug.md)

• **时间测量**: `performance.now()` / `console.time` / Python `timeit` 装饰器
• **内存分析**: Node.js `process.memoryUsage()` / Python `tracemalloc`

前端调试与常见问题

> 详见 [frontend-debug.md](frontend-debug.md)

• **Console 高级方法**: `group` / `table` / `assert` / `trace` / `count`
• **React DevTools**: `displayName` / `useDebugValue`
• **常见 JS 陷阱**: 忘记 await、闭包捕获、this 丢失

调试清单

## 调试前

- [ ] 能稳定复现问题吗？
- [ ] 最小复现用例是什么？
- [ ] 最近改动了什么？

## 调试中

- [ ] 查看错误日志和堆栈
- [ ] 添加必要的日志输出
- [ ] 使用断点逐步执行
- [ ] 检查输入数据是否正确
- [ ] 检查环境变量和配置

## 调试后

- [ ] 修复是否解决了根本原因？
- [ ] 是否需要添加测试？
- [ ] 是否需要更新文档？
- [ ] 是否有类似问题需要检查？

最佳实践

1. **先复现后调试** - 不能复现就无法确认修复 2. **二分法定位** - 缩小问题范围 3. **记录尝试** - 避免重复无效尝试 4. **查看最近改动** - git diff, git log 5. **橡皮鸭调试** - 向他人解释问题 6. **休息一下** - 换个思路 7. **搜索错误信息** - 可能他人遇到过 8. **检查假设** - 你认为正确的可能是错的 9. **简化问题** - 去除无关因素 10. **写测试固化** - 防止问题复现

> **记住**: 调试的第一步是复现——稳定复现问题后，解决方案通常就在眼前。