Debugging

代码调试

When to use this skill

何时使用此技能

Encountering runtime errors or exceptions
Code produces unexpected output or behavior
Performance degradation or memory issues
Intermittent or hard-to-reproduce bugs
Understanding unfamiliar error messages
Post-incident analysis and prevention

遇到运行时错误或异常
代码产生意外输出或行为
性能下降或内存问题
间歇性或难以复现的Bug
理解陌生的错误信息
事后故障分析与预防

Instructions

操作指南

Step 1: Gather Information

步骤1：收集信息

Collect all relevant context about the issue:

Error details:

Full error message and stack trace
Error type (syntax, runtime, logic, etc.)
When did it start occurring?
Is it reproducible?

Environment:

Language and version
Framework and dependencies
OS and runtime environment
Recent changes to code or config

bash

undefined

收集与问题相关的所有上下文：

错误详情：

完整的错误信息和堆栈跟踪
错误类型（语法错误、运行时错误、逻辑错误等）
错误何时开始出现？
是否可复现？

环境信息：

编程语言及版本
框架与依赖库
操作系统与运行环境
代码或配置的最近变更

bash

undefined

Check recent changes

git log --oneline -10 git diff HEAD~5

Check dependency versions

npm list --depth=0 # Node.js pip freeze # Python

undefined

npm list --depth=0 # Node.js pip freeze # Python

undefined

Step 2: Reproduce the Issue

步骤2：复现问题

Create a minimal, reproducible example:

python

undefined

创建最小化的可复现示例：

python

undefined

Bad: Vague description

"The function sometimes fails"

Good: Specific reproduction steps

"""

Call process_data() with input: {"id": None}
Error occurs: TypeError at line 45
Expected: Return empty dict
Actual: Raises exception """

"""

Call process_data() with input: {"id": None}
Error occurs: TypeError at line 45
Expected: Return empty dict
Actual: Raises exception """

Minimal reproduction

def test_reproduce_bug(): result = process_data({"id": None}) # Fails here assert result == {}

undefined

def test_reproduce_bug(): result = process_data({"id": None}) # Fails here assert result == {}

undefined

Step 3: Isolate the Problem

步骤3：定位问题

Use binary search debugging to narrow down the issue:

Print/Log debugging:

python

def problematic_function(data):
    print(f"[DEBUG] Input: {data}")  # Entry point

    result = step_one(data)
    print(f"[DEBUG] After step_one: {result}")

    result = step_two(result)
    print(f"[DEBUG] After step_two: {result}")  # Issue here?

    return step_three(result)

Divide and conquer:

python

undefined

使用二分法调试缩小问题范围：

打印/日志调试：

python

def problematic_function(data):
    print(f"[DEBUG] Input: {data}")  # Entry point

    result = step_one(data)
    print(f"[DEBUG] After step_one: {result}")

    result = step_two(result)
    print(f"[DEBUG] After step_two: {result}")  # Issue here?

    return step_three(result)

分而治之：

python

undefined

Comment out half the code

If error persists: bug is in remaining half

If error gone: bug is in commented half

Repeat until isolated

undefined

undefined

Step 4: Analyze Root Cause

步骤4：分析根本原因

Common bug patterns and solutions:

Pattern	Symptom	Solution
Off-by-one	Index out of bounds	Check loop bounds
Null reference	NullPointerException	Add null checks
Race condition	Intermittent failures	Add synchronization
Memory leak	Gradual slowdown	Check resource cleanup
Type mismatch	Unexpected behavior	Validate types

Questions to ask:

What changed recently?
Does it fail with specific inputs?
Is it environment-specific?
Are there any patterns in failures?

常见Bug模式及解决方案：

模式	症状	解决方案
差一错误	索引越界	检查循环边界
空引用	NullPointerException	添加空值检查
竞态条件	间歇性故障	添加同步机制
内存泄漏	性能逐渐下降	检查资源清理逻辑
类型不匹配	意外行为	验证数据类型

需思考的问题：

最近有哪些变更？
是否仅在特定输入下失败？
是否与环境相关？
故障是否存在规律？

Step 5: Implement Fix

步骤5：实施修复

Apply the fix with proper verification:

python

undefined

应用修复并进行适当验证：

python

undefined

Before: Bug

def get_user(user_id): return users[user_id] # KeyError if not found

After: Fix with proper handling

def get_user(user_id): if user_id not in users: return None # Or raise custom exception return users[user_id]


**Fix checklist**:
- [ ] Addresses root cause, not just symptom
- [ ] Doesn't break existing functionality
- [ ] Handles edge cases
- [ ] Includes appropriate error handling
- [ ] Has test coverage

def get_user(user_id): if user_id not in users: return None # Or raise custom exception return users[user_id]


**修复检查清单**：
- [ ] 针对根本原因修复，而非仅解决表面症状
- [ ] 未破坏现有功能
- [ ] 处理边缘情况
- [ ] 包含适当的错误处理逻辑
- [ ] 有测试覆盖

Step 6: Verify and Prevent

步骤6：验证与预防

Ensure the fix works and prevent regression:

python

undefined

确保修复有效并防止回归：

python

undefined

Add test for the specific bug

def test_bug_fix_issue_123(): """Regression test for issue #123: KeyError on missing user""" result = get_user("nonexistent_id") assert result is None # Should not raise

Add edge case tests

@pytest.mark.parametrize("input,expected", [ (None, None), ("", None), ("valid_id", {"name": "User"}), ]) def test_get_user_edge_cases(input, expected): assert get_user(input) == expected

undefined

@pytest.mark.parametrize("input,expected", [ (None, None), ("", None), ("valid_id", {"name": "User"}), ]) def test_get_user_edge_cases(input, expected): assert get_user(input) == expected

undefined

Examples

示例

Example 1: TypeError debugging

示例1：TypeError调试

Error:

TypeError: cannot unpack non-iterable NoneType object
  File "app.py", line 25, in process
    name, email = get_user_info(user_id)

Analysis:

python

undefined

错误：

TypeError: cannot unpack non-iterable NoneType object
  File "app.py", line 25, in process
    name, email = get_user_info(user_id)

分析与修复：

python

undefined

Problem: get_user_info returns None when user not found

def get_user_info(user_id): user = db.find_user(user_id) if user: return user.name, user.email # Missing: return None case!

Fix: Handle None case

def get_user_info(user_id): user = db.find_user(user_id) if user: return user.name, user.email return None, None # Or raise UserNotFoundError

undefined

def get_user_info(user_id): user = db.find_user(user_id) if user: return user.name, user.email return None, None # Or raise UserNotFoundError

undefined

Example 2: Race condition debugging

示例2：竞态条件调试

Symptom: Test passes locally, fails in CI intermittently

Analysis:

python

undefined

症状：本地测试通过，CI中间歇性失败

分析与修复：

python

undefined

Problem: Shared state without synchronization

class Counter: def init(self): self.value = 0

def increment(self):
    self.value += 1  # Not atomic!

class Counter: def init(self): self.value = 0

def increment(self):
    self.value += 1  # Not atomic!

Fix: Add thread safety

import threading

class Counter: def init(self): self.value = 0 self._lock = threading.Lock()

def increment(self):
    with self._lock:
        self.value += 1

undefined

import threading

class Counter: def init(self): self.value = 0 self._lock = threading.Lock()

def increment(self):
    with self._lock:
        self.value += 1

undefined

Example 3: Memory leak debugging

示例3：内存泄漏调试

Tool: Use memory profiler

python

from memory_profiler import profile

@profile
def process_large_data():
    results = []
    for item in large_dataset:
        results.append(transform(item))  # Memory grows
    return results

工具：使用内存分析器

python

from memory_profiler import profile

@profile
def process_large_data():
    results = []
    for item in large_dataset:
        results.append(transform(item))  # Memory grows
    return results

Fix: Use generator for large datasets

def process_large_data(): for item in large_dataset: yield transform(item) # Memory efficient

undefined

def process_large_data(): for item in large_dataset: yield transform(item) # Memory efficient

undefined

Best practices

最佳实践

Reproduce first: Never fix what you can't reproduce
One change at a time: Isolate variables when debugging
Read the error: Error messages usually point to the issue
Check assumptions: Verify what you think is true
Use version control: Easy to revert and compare changes
Document findings: Help future debugging efforts
Write tests: Prevent regression of fixed bugs

先复现问题：永远不要修复无法复现的问题
一次只改一处：调试时隔离变量
阅读错误信息：错误信息通常指向问题所在
验证假设：确认你认为正确的内容是否真的成立
使用版本控制：便于回滚和对比变更
记录发现：为未来的调试工作提供帮助
编写测试：防止已修复的Bug回归

Debugging Tools

调试工具

Language	Debugger	Profiler
Python	pdb, ipdb	cProfile, memory_profiler
JavaScript	Chrome DevTools	Performance tab
Java	IntelliJ Debugger	JProfiler, VisualVM
Go	Delve	pprof
Rust	rust-gdb	cargo-flamegraph

编程语言	调试器	性能分析器
Python	pdb, ipdb	cProfile, memory_profiler
JavaScript	Chrome DevTools	Performance tab
Java	IntelliJ Debugger	JProfiler, VisualVM
Go	Delve	pprof
Rust	rust-gdb	cargo-flamegraph

debugging

Original

Translation

Debugging

代码调试

When to use this skill

何时使用此技能

Instructions

操作指南

Step 1: Gather Information

步骤1：收集信息

Check recent changes

Check recent changes

Check dependency versions

Check dependency versions

Step 2: Reproduce the Issue

步骤2：复现问题

Bad: Vague description

Bad: Vague description

Good: Specific reproduction steps

Good: Specific reproduction steps

Minimal reproduction

Minimal reproduction

Step 3: Isolate the Problem

步骤3：定位问题

Comment out half the code

Comment out half the code

If error persists: bug is in remaining half

If error persists: bug is in remaining half

If error gone: bug is in commented half

If error gone: bug is in commented half

Repeat until isolated

Repeat until isolated

Step 4: Analyze Root Cause

步骤4：分析根本原因

Step 5: Implement Fix

步骤5：实施修复

Before: Bug

Before: Bug

After: Fix with proper handling

After: Fix with proper handling

Step 6: Verify and Prevent

步骤6：验证与预防

Add test for the specific bug

Add test for the specific bug

Add edge case tests

Add edge case tests

Examples

示例

Example 1: TypeError debugging

示例1：TypeError调试

Problem: get_user_info returns None when user not found

Problem: get_user_info returns None when user not found

Fix: Handle None case

Fix: Handle None case

Example 2: Race condition debugging

示例2：竞态条件调试

Problem: Shared state without synchronization

Problem: Shared state without synchronization

Fix: Add thread safety

Fix: Add thread safety

Example 3: Memory leak debugging

示例3：内存泄漏调试

Fix: Use generator for large datasets

Fix: Use generator for large datasets

Best practices

最佳实践

Debugging Tools

调试工具

References

参考资料