# Ac Debug

> 问题诊断：定位报错与异常根因，按需并行取证，并在用户确认后执行最小修复与验证。

- Skill: `yz0812/ac-debug` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yz0812/ac-debug`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yz0812/ac-debug/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yz0812 (https://skillmd.com/u/yz0812)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yz0812/ac-debug

---


# Debug - 主线程诊断 + Subagents 取证

定位问题根因，必要时由 Claude 主线程统筹多个 subagents 并行取证；最终诊断、用户沟通、代码修复与验证均由主线程完成。

## 使用方法

```bash
/ac-debug <问题描述>
```

## 角色分工

| 角色 | 职责 |
|------|------|
| Claude（主线程） | 收集问题、决定是否启用 subagents、整合证据、输出诊断、等待确认、执行修复 |
| subagents | 并行检索调用链、日志线索、配置/测试影响等证据，不修改代码 |

---

## 执行约束

**工作目录**：
- 如果用户通过 `/add-dir` 添加了多个工作区，先用 Glob/Grep 确定任务相关的工作区
- 如果无法确定，用 `AskUserQuestion` 询问用户选择目标工作区
- 在当前会话内完成诊断与修复，不依赖外部模型或额外会话

**subagents 使用条件**：
- 适用：错误路径不清、涉及多个模块、日志/堆栈很多、需要并行排查多个方向
- 优先：使用只读 subagents 做调用链检索、错误点上下文收集、配置/测试影响分析
- 不适用：报错点明确、单文件小问题、两三次检索即可收敛的简单问题

**重要**：
- 不调用任何外部模型、后台任务或额外 Bash 编排
- subagents 只做检索与取证，不做代码修改，不直接给用户下最终结论
- 已委托给 subagents 的搜索或分析内容，主线程不要重复执行
- 最终诊断结论必须由主线程统一输出
- 修复前必须先向用户展示诊断结果并等待确认

---

## 执行工作流

**问题描述**：$ARGUMENTS

### 🔍 阶段 0：Prompt 增强（可选）

`[模式：准备]`

分析 $ARGUMENTS 的意图、缺失信息、隐含假设，补全为结构化需求（明确目标、技术约束、范围边界、验收标准），后续诊断时优先使用增强后的需求。

### 🔎 阶段 1：上下文收集与并行取证

`[模式：研究]`

1. 主线程先收集最小必要信息：错误日志、堆栈、复现步骤、相关文件
2. 若问题较简单，直接继续诊断
3. 若问题跨模块或线索很多，按需并行启动 subagents，典型拆分为：
   - **调用链排查**：定位报错路径、入口和相关调用方
   - **证据收集**：整理日志、堆栈、异常分支、边界条件
   - **影响面排查**：检查配置、测试、依赖模块、最近改动的关联面
4. subagents 返回证据、定位和可疑点后，由主线程统一收集

### 🔬 阶段 2：主线程诊断

`[模式：诊断]`

1. 基于主线程与 subagents 收集到的证据进行诊断
2. 输出诊断假设（按可能性排序），每个假设包含：
   - 原因
   - 证据
   - 验证方式
   - 修复建议
3. 必要时补充一轮定向检索，直到诊断范围收敛

### 🔀 阶段 3：假设整合

`[模式：验证]`

1. 交叉验证代码、日志、堆栈与复现步骤
2. 筛选 **Top 1-2 最可能原因**
3. 明确最小修复路径与验证策略

### ⛔ 阶段 4：用户确认（Hard Stop）

`[模式：确认]`

```markdown
## 🔍 诊断结果

### 关键证据
- <证据 1>
- <证据 2>

### 综合诊断
**最可能原因**：<具体诊断>
**验证方案**：<如何确认>
**修复方向**：<准备怎么改>

---
**确认后我将执行修复。是否继续？(Y/N)**
```

**⚠️ 必须等待用户确认后才能进入阶段 5**

### 🔧 阶段 5：修复与验证

`[模式：执行]`

用户确认后：
1. 由主线程根据诊断实施修复
2. 运行最小相关范围的测试或验证步骤
3. 若验证失败，先修复回归问题再交付

---

## 关键规则

1. **证据优先** – 以代码、日志、堆栈与复现信息为准
2. **主线程收口** – 最终诊断、修复与验证均由当前会话主线程完成
3. **subagents 只做取证辅助** – 按需使用，不默认开启，不修改代码
4. **用户确认后修复** – 修复前必须获得确认