deep-debug
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDeep 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
命令
| Command | Purpose |
|---|---|
| Guided debugging workflow with evidence gathering and parallel investigation |
| 命令 | 用途 |
|---|---|
| 带证据收集和并行调查功能的引导式调试工作流 |
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_pageFor 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:
| Signal | Meaning |
|---|---|
| All 3 agree on root cause | High confidence - fix it |
| 2 agree, 1 different | Investigate the difference |
| All 3 different | Need 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
并行调查结果
| Agent | Finding |
|---|---|
| debugger | |
| code-reviewer | Same finding + explained React pattern causing it |
| Explore | Verified UI layer wasn't double-calling (ruled out) |
| Agent | 调查结果 |
|---|---|
| debugger | |
| code-reviewer | 与上述结论一致,并解释了引发该问题的React模式 |
| Explore | 验证UI层未触发重复调用(排除该可能性) |
Root Cause (Consensus)
根因(共识结论)
sendMessagestate.messagessendMessagestate.messagesFix
修复方案
Use to access current state without including in dependencies:
stateReftypescript
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 */]);使用访问当前状态,无需将其纳入依赖项:
stateReftypescript
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问题
- in useCallback dependencies causing recreation
state - 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工具速查
| Tool | Use For |
|---|---|
| See all fetch/XHR calls, duplicates, failures |
| Errors, warnings, debug logs |
| Current DOM state |
| Execute debug code in page context |
| 工具 | 用途 |
|---|---|
| 查看所有fetch/XHR调用、重复请求、失败请求 |
| 查看错误、警告、调试日志 |
| 查看当前DOM状态 |
| 在页面上下文执行调试代码 |
Tips for Success
成功调试小贴士
- Evidence first, hypotheses second - Don't guess until you have concrete data
- Network tab is gold - Most frontend bugs show symptoms there
- Parallel agents save time - 3 perspectives at once vs sequential guessing
- Cross-reference findings - Agreement = confidence
- Verify with same evidence - Confirm fix with same tools that found bug
- 先取证,后假设 - 拿到具体数据前不要盲目猜测
- Network面板是黄金线索 - 大多数前端Bug的症状都会在这里体现
- 并行Agent节省时间 - 同时获取3种视角,替代逐一排查
- 交叉验证结果 - 多Agent结论一致意味着可信度高
- 用相同证据验证修复 - 用发现Bug的同一套工具确认修复效果