AgentSkillsCN

debugging

以假设驱动的调试进行系统调查。识别根本原因，创建最小复现，实施修复。在调查错误、漏洞、崩溃或意外行为时使用此方法。

SKILL.md
--- frontmatter
name: debugging
description: Hypothesis-driven debugging with systematic investigation. Identifies root causes, creates minimal reproductions, and implements fixes. Use when investigating errors, bugs, crashes, or unexpected behavior.

Debugging

Systematic debugging using hypothesis testing and root cause analysis.

When to Use

  • •Error investigation (exceptions, crashes)
  • •Unexpected behavior diagnosis
  • •Performance issue root cause
  • •Integration/dependency failures

MCP Workflow

code
# 1. Get code at error location
serena.find_symbol(name_path="ErrorClass/method", include_body=True)

# 2. Trace call chain
serena.find_referencing_symbols(name_path="ErrorClass/method")

# 3. Search for similar patterns
serena.search_for_pattern("null.*check|error.*handling", relative_path="src/")

# 4. Check past similar issues
claude-mem.search(query="<error-type>", project="<project>")

# 5. Framework error handling
context7.get-library-docs("<framework>", topic="exception handling")

Workflow

1. Observe

code
- Error message and stack trace
- Steps to reproduce
- When did it start? (recent changes?)
- Scope (one user? all?)

2. Hypothesize

code
Based on: [observation]
Hypothesis: [proposed cause]
Test: [how to verify]

3. Test

code
serena.find_symbol("SuspectedClass/method", include_body=True)
serena.find_referencing_symbols("SuspectedCause")
# Log analysis, local reproduction

4. Fix

code
1. Write failing test that reproduces bug
2. Implement minimal fix
3. Verify test passes
4. Run full test suite

5. Prevent

code
- Add edge case tests
- Improve validation
- Update documentation

Common Patterns

Null/Undefined

Symptoms: NullPointerException, "undefined is not a function" Investigate:

  • •Find where null originates
  • •Trace back through call chain
  • •Check data presence assumptions

Race Condition

Symptoms: Intermittent, works in debug mode Red flags:

  • •Shared mutable state
  • •Missing synchronization
  • •Execution order assumptions

Data Inconsistency

Investigate:

  • •Trace data flow source to error
  • •Check transformation logic
  • •Verify cache invalidation

Investigation Techniques

Git Bisect

bash
git bisect start
git bisect bad
git bisect good <commit>
# Test middle commit, mark good/bad
git bisect reset

Stack Trace Analysis

code
Start at bottom (entry point)
Move up to error line
Examine code at that line
Check what could be null/invalid

Divide and Conquer

code
A -> B -> C -> D (output wrong)
Check B: correct? -> problem in C or D
        wrong?   -> problem in A or B

Output Format

markdown
## Bug: [Title]

### Symptoms
- Error: [message]
- Location: `file:line`

### Investigation
**Hypothesis 1:** [description]
- Test: [method]
- Result: Confirmed / Ruled Out

### Root Cause
[Identified cause] at `file:line`

### Fix
[Description]

### Prevention
- [ ] Test added
- [ ] Similar patterns checked

Checklist

  • • Can reproduce consistently
  • • Stack trace analyzed
  • • Root cause identified (not just symptom)
  • • Failing test written
  • • Fix implemented
  • • Full test suite passes