run-parallel-agents-feature-debug

此技能负责协调实际的 Agent 工具执行。以下规则不可妥协： 1. 并行处理前，先证明这些故障并非由同一个根因导致。 2. 为每个启动的 Agent 编写完整提示词，因为新建的 `subagent_type` Agent 不会继承任务上下文。 3. 在同一条 assistant 消息中，通过多个 `Agent(...)` 工具调用启动所有并行 Agent。 4. 对相互独立的调试任务使用 `run_in_background: true`，且不要轮询后台输出。 5. 对可能修改代码的调试任务使用 `isolation: "worktree"`。

并行 Agent 调试功能

输入

• $request：可选的问题集、故障列表或用户指示，例如 并行调试这三个失败的测试套件 或 把这些 Bug 分配给多个 Agent。

目标

利用 Claude Code 的真实并行 Agent 运行时，并发诊断和修复相互独立的故障，同时避免将同一个根因拆成多个相互冲突的调查任务。

步骤 0：确定候选调试任务

确定故障集：

• 用户明确列出的问题
• 失败的测试组
• 出故障的子系统
• 按组归类的编译、Lint、运行时或性能故障

然后确定：

• 故障数量
• 可能的子系统边界
• 每个故障是某个症状，还是独立问题
• 这些任务是否属于调试和修复，而非规划或广泛探索

以下情况不要使用此技能：

• 独立任务少于 3 个
• 多个故障可能具有相同根因
• 某个故障依赖项、配置值、架构变更或部署事件可能解释多个症状
• 执行前仍需先拆解任务

仅当安全归类取决于用户澄清时，才使用 AskUserQuestion。

成功标准：得到一组具体的候选调试任务，值得进一步判断其独立性。

步骤 1：证明任务相互独立，排除共享根因陷阱

针对每个候选任务，检查：

• 该故障是否与其他任务同时开始
• 多条错误追踪中是否出现相同的依赖项、配置、迁移、环境或上游服务
• 一项修复是否可能同时消除多个症状
• 如果多个任务都进入修复阶段，其修改范围是否互不重叠

仅在以下条件都满足时才并行处理：

• 根因可能不同
• 复现范围仅限于各自任务
• 预期修复不会大量重叠

如果存在实质性疑虑，暂时不要并行处理。先诊断共享根因。

加载 references/debug_patterns.md，了解根因判断启发和特定框架的故障模式。 加载 references/agent-runtime-semantics.md，了解影响并行调试执行成败的运行时规则。

成功标准：每个选定任务在诊断和修复阶段都可能相互独立。

步骤 2：为每个调试任务匹配合适的 Agent

根据以下因素，为每个任务选择最合适的专用 Agent：

• 框架和语言
• 失败文件和目录
• 错误特征
• 任务侧重运行时、测试、构建还是性能

加载 references/agent_matching_logic.md，了解详细的匹配规则和边缘情况。

实用默认规则：

• 使用最匹配的框架或领域专用 Agent
• 只有在没有更合适的选择时才使用 general-purpose
• 不要编造 Agent 类型

成功标准：为每个任务分配有充分依据的调试 Agent。

第 3 步：编写完整的调试简报

由于新启动的 subagent_type Agent 不会获得主线程的任务上下文，因此每条提示词都必须包含：

• 准确的问题描述
• 具体错误或症状
• 复现步骤（如已知）
• 受影响的文件或目录
• 可能的范围边界
• 成功的判定标准
• 必需的验证命令或测试
• 此任务是只诊断，还是诊断并修复

优先提供实际证据，而非摘要：

• 失败命令的输出
• 堆栈跟踪摘录
• 失败的测试名称
• 受影响的文件路径

不要只给新 Agent 含糊的指示，例如“修复这套测试”，却不说明具体的失败情况。

成功标准：每条任务提示词都足够完整，让新 Agent 无需先提出基本问题即可开始诊断。

第 4 步：在同一个并行批次中启动所有 Agent

在一条包含多个 Agent(...) 工具调用的助手消息中，启动所有任务线。

可执行修复的调试任务线必须满足以下启动语义：

• subagent_type：匹配的 Agent 类型
• description：简短的 3-5 词描述
• prompt：完整的调试简报
• run_in_background: true
• isolation: "worktree"

运行时特定规则：

• 如果用户要求并行调试，不要把启动操作拆分到多条助手消息中
• 并行安全性至关重要时，不要依赖目标 Agent 的默认异步或隔离设置
• 此技能适用于新启动的专业调试 Agent，不要使用只读分支

请加载 references/agent-runtime-semantics.md，了解这些规则背后有依据的具体原因。

成功标准：所有相互独立的调试任务线都已并发启动，并明确设置了安全的运行时参数。

第 5 步：汇总完成情况，不轮询

启动后：

• 继续处理不重叠的协调工作
• 等待完成通知，而不是轮询后台记录
• 除非有具体理由需要深入检查，否则采信返回的 Agent 摘要

每条任务线完成时，记录：

• 状态
• 诊断出的根本原因
• 修改的文件
• 验证结果
• 阻碍或未解决的范围

如果某条任务线得出结论，认为问题实际上并不独立，请停止把最初的分类视为有效，并重新界定剩余工作。

成功标准：每个已启动的任务线都有结果记录，且没有产生不必要的记录噪声。

第 6 步：验证修复并检查冲突

在将并行调试会话视为完成之前：

• 对每条任务线重新运行原先失败的测试或验证命令
• 确认原始症状确实已消失
• 检查文件修改是否重叠，修复是否相互矛盾
• 确认某条任务线没有悄悄破坏另一条任务线负责的子系统

如果存在冲突：

• 停止自动汇总
• 找出重叠的文件或相互矛盾的修复
• 有意合并，或将问题上报给用户

如果多条任务线找到了相同的根本原因：

• 明确说明
• 整合结果，不要假装这是多个独立的成果

成功标准：最终结果反映的是真正修复，而不只是并行尝试过的补丁。

第 7 步：汇报整合后的结果

总结：

• 执行了哪些调试任务线
• 各任务线由哪些 Agent 负责
• 每条任务线的根本原因和修复状态
• 每条任务线的验证结果
• 冲突、相同的根本原因或剩余阻碍

如有部分成功，请明确说明。只有当原始故障确实已解决，或其范围已明确重新界定，调试才算完成。

成功标准：用户获得简洁、准确的并行调试摘要。

防护措施

• 少于 3 条真正独立的排查路径时，不要使用此技能。
• 可能存在相同根因的症状不要并行处理。
• 不要将大型示例、评分表或框架目录直接放在 SKILL.md 中。
• 不要假设新启动的 Agent 了解周边任务的上下文。
• 除非用户明确要求，否则不要轮询或持续读取后台 Agent 的输出。
• 显式启动参数更稳妥时，不要依赖 Agent 默认的 background 或 isolation 设置。
• 不要添加 disable-model-invocation；用户要求并行调试时，此技能应仍可用。
• 不要添加 context: fork；此工作流用于协调新启动的专业 Agent，而非创建只读技能分支。
• 不要添加 paths:；这是一个通用的编排技能。

何时加载参考资料

• references/agent-runtime-semantics.md 用于了解有来源依据的 Agent 运行时规则：新上下文、单消息并行启动、后台行为、工作树隔离和显式参数优先级。

• references/debug_patterns.md 用于了解共享根因的启发式方法、特定框架的错误模式和分诊指导。

• references/agent_matching_logic.md 用于了解详细的 Agent 选择规则和特定框架的边缘情况。

输出约定

报告：

1. 已确定的排查路径集合
2. 每条路径对应的 Agent 分配
3. 启动状态
4. 每条路径的根因和修复状态
5. 验证结果
6. 冲突、发现的共享根因或仍未解决的阻碍