deep-debug（深度调试）

Deep Debug - Multi-Agent Investigation

Status: Production Ready Last Updated: 2026-02-03 Dependencies: Chrome MCP tools (optional), debugger agent, code-reviewer agent

When to Use

• Going in circles - You've tried multiple fixes but nothing works
• Browser + API interaction bugs - Need to see Network tab, console logs
• Symptoms don't match expectations - Something deeper is wrong
• Complex state management bugs - React hooks, closures, race conditions

Commands

Quick Start

/debug [description of the bug]

Or invoke naturally:

• "I'm stuck on this bug, can you do a deep investigation?"
• "This bug is resisting normal debugging"
• "I need you to really dig into this"

The Process

Phase 1: Gather Evidence (Before Hypothesizing)

For browser-related bugs, use Chrome MCP tools:

// Get network requests (look for duplicates, failures, timing)
mcp__claude-in-chrome__read_network_requests

// Get console logs (errors, warnings, debug output)
mcp__claude-in-chrome__read_console_messages

// Get page state
mcp__claude-in-chrome__read_page

For backend bugs, gather:

• Error logs and stack traces
• Request/response payloads
• Database query logs
• Timing information

Phase 2: Launch Parallel Investigation (3 Agents)

Launch these agents simultaneously with the gathered evidence:

Agent 1: Execution Tracer (debugger)

Task(subagent_type="debugger", prompt="""
EVIDENCE: [paste network/console evidence]

Trace the execution path that leads to this bug. Find:
1. Where the bug originates
2. What triggers it
3. The exact line/function causing the issue

Focus on TRACING, not guessing.
""")

Agent 2: Pattern Analyzer (code-reviewer)

Task(subagent_type="code-reviewer", prompt="""
EVIDENCE: [paste evidence]

Review the relevant code for common bug patterns:
- React useCallback/useMemo dependency issues
- Stale closures
- Race conditions
- State update ordering
- Missing error handling

Find patterns that EXPLAIN the evidence.
""")

Agent 3: Entry Point Mapper (Explore)

Task(subagent_type="Explore", prompt="""
EVIDENCE: [paste evidence]

Map all entry points that could trigger this behavior:
- All places [function] is called
- All event handlers involved
- All state updates that affect this

Find if something is being called MULTIPLE TIMES or from UNEXPECTED places.
""")

Phase 3: Cross-Reference Findings

After agents complete, look for:

Phase 4: Verify Fix

After implementing the fix, re-gather the same evidence to confirm:

• Network tab shows expected behavior
• Console has no errors
• State updates correctly

Real Example: Duplicate API Calls Bug

Evidence Gathered

Network tab showed 2 fetch requests for the same message.

Parallel Investigation Results

Root Cause (Consensus)

sendMessage useCallback had state.messages in dependency array. Every state update recreated the callback, causing duplicate calls during React re-renders.

Fix

Use stateRef to access current state without including in dependencies:

const stateRef = useRef(state);
stateRef.current = state;

const sendMessage = useCallback(async (text) => {
  // Use stateRef.current instead of state
  const messages = stateRef.current.messages;
  // ...
}, [/* state.messages removed */]);

Common Bug Patterns This Catches

React Hook Issues

• state in useCallback dependencies causing recreation
• Missing dependencies causing stale closures
• useEffect running multiple times

API/Network Issues

• Duplicate requests (visible in Network tab)
• Race conditions between requests
• CORS failures
• Timeout handling

State Management Issues

• State updates not batching correctly
• Optimistic updates conflicting with server response
• Multiple sources of truth

Chrome Tools Quick Reference

Tips for Success

1. Evidence first, hypotheses second - Don't guess until you have concrete data
2. Network tab is gold - Most frontend bugs show symptoms there
3. Parallel agents save time - 3 perspectives at once vs sequential guessing
4. Cross-reference findings - Agreement = confidence
5. Verify with same evidence - Confirm fix with same tools that found bug