Locate the root cause of the problem; when necessary, the Claude main thread coordinates multiple subagents to gather evidence in parallel; final diagnosis, user communication, code fixes, and verification are all handled by the main thread.
How to Use
/ac-debug <问题描述>
Role Division
| Role | Responsibilities |
|---|---|
| Claude (Main Thread) | Collect the problem, decide whether to enable subagents, integrate evidence, output the diagnosis, wait for confirmation, perform the fix |
| subagents | Retrieve evidence such as call chains, log clues, and configuration/test impact in parallel, without modifying code |
Execution Constraints
Working Directory:
- If the user has added multiple workspaces via
/add-dirfirst use Glob/Grep to determine the workspace relevant to the task - If it cannot be determined, use
AskUserQuestionto ask the user to select the target workspace - Complete diagnosis and fixing within the current session, without relying on external models or additional sessions
Conditions for Using subagents:
- Applicable: the error path is unclear, multiple modules are involved, there are many logs/stack traces, and multiple directions need to be investigated in parallel
- Preferred: use read-only subagents for call-chain retrieval, error-point context collection, and configuration/test impact analysis
- Not applicable: the error point is clear, it is a small single-file problem, or a simple problem that can converge with two or three searches
Important:
- Do not call any external models, background tasks, or additional Bash orchestration
- subagents only perform retrieval and evidence gathering, do not modify code, and do not directly give the user a final conclusion
- For search or analysis content already delegated to subagents, the main thread should not repeat it
- The final diagnostic conclusion must be output uniformly by the main thread
- Before fixing, the diagnostic results must first be shown to the user and confirmation awaited
Execution Workflow
Problem Description:$ARGUMENTS
🔍 Phase 0: Prompt enhancement (optional)
[模式:准备]
Analyze the intent, missing information, and implicit assumptions of $ARGUMENTS, and complete them into structured requirements (clear goals, technical constraints, scope boundaries, acceptance criteria); during subsequent diagnosis, prioritize the enhanced requirements.
🔎 Phase 1: Context collection and parallel evidence gathering
[模式:研究]
- The main thread first collects the minimal necessary information: error logs, stack traces, reproduction steps, related files
- If the problem is relatively simple, continue diagnosis directly
- If the problem spans modules or there are many clues, start subagents in parallel as needed, typically split into:
- Call-chain investigation: locate the error path, entry points, and related callers
- Evidence collection: organize logs, stack traces, exception branches, and boundary conditions
- Impact-scope investigation: check configuration, tests, dependent modules, and the related surface of recent changes
- After subagents return evidence, locations, and suspicious points, the main thread collects them uniformly
🔬 Phase 2: Main-thread diagnosis
[模式:诊断]
- Diagnose based on the evidence collected by the main thread and subagents
- Output diagnostic hypotheses (sorted by likelihood), each hypothesis including:
- Cause
- Evidence
- Verification method
- Fix suggestion
- Supplement with a round of targeted retrieval when necessary until the diagnostic scope converges
🔀 Phase 3: Hypothesis Integration
[模式:验证]
- Cross-validate code, logs, stack traces, and reproduction steps
- Filter Top 1-2 most likely causes
- Define the minimal fix path and validation strategy
⛔ Phase 4: User Confirmation (Hard Stop)
[模式:确认]
## 🔍 诊断结果
### 关键证据
- <证据 1>
- <证据 2>
### 综合诊断
**最可能原因**:<具体诊断>
**验证方案**:<如何确认>
**修复方向**:<准备怎么改>
---
**确认后我将执行修复。是否继续?(Y/N)**
⚠️ Must wait for user confirmation before proceeding to Phase 5
🔧 Phase 5: Fix and Validation
[模式:执行]
After user confirmation:
- The main thread implements the fix based on the diagnosis
- Run tests or validation steps for the minimal relevant scope
- If validation fails, fix the regression issue first before delivery
Key Rules
- Evidence first – Base decisions on code, logs, stack traces, and reproduction information
- Main thread closes the loop – The final diagnosis, fix, and validation are all completed by the main thread of the current session
- Subagents only assist with evidence gathering – Use as needed, not enabled by default, and do not modify code
- Fix after user confirmation – Confirmation must be obtained before fixing