deep-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deep Debug - Multi-Agent Investigation

Deep Debug - Multi-Agent Investigation

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

状态:已就绪可投入生产使用 最后更新时间:2026-02-03 依赖项:Chrome MCP工具(可选)、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
  • 调试陷入死循环 - 尝试了多种修复方案但均无效
  • 浏览器+API交互类Bug - 需要查看Network面板、控制台日志
  • 症状与预期不符 - 存在更深层次的问题
  • 复杂状态管理类Bug - React hooks、闭包、竞态条件问题

Commands

命令

CommandPurpose
/debug
Guided debugging workflow with evidence gathering and parallel investigation
命令用途
/debug
带证据收集和并行调查功能的引导式调试工作流

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"

/debug [Bug描述]
或自然语言调用:
  • "我在这个Bug上卡住了,能帮我做深度调查吗?"
  • "这个Bug用常规调试方法解决不了"
  • "我需要你深入排查这个问题"

The Process

调试流程

Phase 1: Gather Evidence (Before Hypothesizing)

阶段1:收集证据(先取证,后假设)

For browser-related bugs, use Chrome MCP tools:
typescript
// 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
针对浏览器相关Bug,使用Chrome MCP工具:
typescript
// 获取网络请求(检查重复请求、失败请求、请求时序)
mcp__claude-in-chrome__read_network_requests

// 获取控制台日志(错误、警告、调试输出)
mcp__claude-in-chrome__read_console_messages

// 获取页面状态
mcp__claude-in-chrome__read_page
针对后端Bug,收集以下信息:
  • 错误日志和堆栈跟踪
  • 请求/响应载荷
  • 数据库查询日志
  • 时序信息

Phase 2: Launch Parallel Investigation (3 Agents)

阶段2:启动并行调查(3个Agent)

Launch these agents simultaneously with the gathered evidence:
结合收集到的证据,同时启动以下3个Agent:

Agent 1: Execution Tracer (debugger)

Agent 1:执行追踪器(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.
""")
Task(subagent_type="debugger", prompt="""
EVIDENCE: [粘贴网络/控制台证据]

追踪导致该Bug的执行路径。需找出:
1. Bug的起源位置
2. Bug的触发条件
3. 引发问题的具体代码行/函数

专注于追踪,而非猜测。
""")

Agent 2: Pattern Analyzer (code-reviewer)

Agent 2:模式分析器(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.
""")
Task(subagent_type="code-reviewer", prompt="""
EVIDENCE: [粘贴证据]

检查相关代码中常见的Bug模式:
- React useCallback/useMemo依赖项问题
- 过期闭包
- 竞态条件
- 状态更新顺序问题
- 缺失错误处理

找出能够解释证据的模式。
""")

Agent 3: Entry Point Mapper (Explore)

Agent 3:入口点映射器(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.
""")
Task(subagent_type="Explore", prompt="""
EVIDENCE: [粘贴证据]

映射所有可能触发该行为的入口点:
- [函数]的所有调用位置
- 涉及的所有事件处理器
- 影响该行为的所有状态更新

检查是否存在函数被多次调用或从意外位置调用的情况。
""")

Phase 3: Cross-Reference Findings

阶段3:交叉验证调查结果

After agents complete, look for:
SignalMeaning
All 3 agree on root causeHigh confidence - fix it
2 agree, 1 differentInvestigate the difference
All 3 differentNeed more evidence
Agent完成调查后,关注以下信号:
信号含义
3个Agent均认同根因可信度高 - 直接修复
2个Agent认同,1个持不同结论深入调查分歧点
3个Agent结论均不同需要收集更多证据

Phase 4: Verify Fix

阶段4:验证修复方案

After implementing the fix, re-gather the same evidence to confirm:
  • Network tab shows expected behavior
  • Console has no errors
  • State updates correctly

实施修复后,重新收集相同证据以确认:
  • Network面板显示符合预期的行为
  • 控制台无错误
  • 状态更新正常

Real Example: Duplicate API Calls Bug

实际案例:重复API调用Bug

Evidence Gathered

收集到的证据

Network tab showed 2 fetch requests for the same message.
Network面板显示针对同一消息发起了2次fetch请求

Parallel Investigation Results

并行调查结果

AgentFinding
debugger
state.messages
in useCallback deps causes callback recreation
code-reviewerSame finding + explained React pattern causing it
ExploreVerified UI layer wasn't double-calling (ruled out)
Agent调查结果
debugger
state.messages
被纳入useCallback依赖项,导致回调函数被重复创建
code-reviewer与上述结论一致,并解释了引发该问题的React模式
Explore验证UI层未触发重复调用(排除该可能性)

Root Cause (Consensus)

根因(共识结论)

sendMessage
useCallback had
state.messages
in dependency array. Every state update recreated the callback, causing duplicate calls during React re-renders.
sendMessage
函数的useCallback依赖数组中包含
state.messages
。每次状态更新都会重新创建该回调函数,导致React重渲染期间出现重复调用。

Fix

修复方案

Use
stateRef
to access current state without including in dependencies:
typescript
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 */]);

使用
stateRef
访问当前状态,无需将其纳入依赖项:
typescript
const stateRef = useRef(state);
stateRef.current = state;

const sendMessage = useCallback(async (text) => {
  // 使用stateRef.current替代state
  const messages = stateRef.current.messages;
  // ...
}, [/* 移除state.messages */]);

Common Bug Patterns This Catches

该方案可排查的常见Bug类型

React Hook Issues

React Hook问题

  • state
    in useCallback dependencies causing recreation
  • Missing dependencies causing stale closures
  • useEffect running multiple times
  • useCallback依赖项中包含
    state
    导致函数重复创建
  • 缺失依赖项引发过期闭包
  • useEffect多次执行

API/Network Issues

API/网络问题

  • Duplicate requests (visible in Network tab)
  • Race conditions between requests
  • CORS failures
  • Timeout handling
  • 重复请求(可在Network面板中查看)
  • 请求间的竞态条件
  • CORS失败
  • 超时处理问题

State Management Issues

状态管理问题

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

  • 状态更新未正确批处理
  • 乐观更新与服务器响应冲突
  • 多数据源不一致

Chrome Tools Quick Reference

Chrome工具速查

ToolUse For
read_network_requests
See all fetch/XHR calls, duplicates, failures
read_console_messages
Errors, warnings, debug logs
read_page
Current DOM state
javascript_tool
Execute debug code in page context

工具用途
read_network_requests
查看所有fetch/XHR调用、重复请求、失败请求
read_console_messages
查看错误、警告、调试日志
read_page
查看当前DOM状态
javascript_tool
在页面上下文执行调试代码

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
  1. 先取证,后假设 - 拿到具体数据前不要盲目猜测
  2. Network面板是黄金线索 - 大多数前端Bug的症状都会在这里体现
  3. 并行Agent节省时间 - 同时获取3种视角,替代逐一排查
  4. 交叉验证结果 - 多Agent结论一致意味着可信度高
  5. 用相同证据验证修复 - 用发现Bug的同一套工具确认修复效果