run-parallel-agents-feature-build

此技能会协调真实的 Agent 工具执行。以下规则不可妥协： 1. 启动任何任务前，先确认任务彼此独立。 2. 为每个启动的 Agent 编写完整提示词，因为新启动的 `subagent_type` Agent 不会继承任务上下文。 3. 在一条助手消息中，通过多个 `Agent(...)` 工具调用启动所有并行 Agent。 4. 对相互独立的任务使用 `run_in_background: true`，且不要轮询或查看后台输出。 5. 对编写代码的任务使用 `isolation: "worktree"`，除非任务明确只读。

并行 Agent 功能开发

输入

• $request：可选的计划路径、任务选择或用户指示，例如 execute layer 0 from .ulpi/plans/foo.json 或 build these three features in parallel。

目标

利用 Claude Code 的真实并行 Agent 运行时，同时执行彼此独立的开发任务，避免文件冲突、上下文缺失或虚假编排。

步骤 0：确定候选任务集

确定任务的权威来源：

• 已批准的 DAG 计划
• 用户明确列出的任务
• 已清晰拆分为相互独立实施任务的工作集

然后确定：

• 任务数量
• 依赖关系
• 写入范围是否重叠
• 每个任务是否属于开发工作，而非研究或调试

出现以下情况时，请勿使用此技能：

• 相互独立的任务少于 3 个
• 任一任务依赖另一任务的结果
• 多个任务会修改同一文件或同一狭窄子系统
• 任务仍处于规划或探索阶段

只有在任务拆分不明确，且安全并行执行取决于用户选择时，才使用 AskUserQuestion。

成功标准：确定一组可安全并行执行的具体开发任务。

步骤 1：验证独立性，而非想当然

对每个候选任务，确认：

• 所需输入已具备
• 无需等待其他任务的输出
• 写入范围互不重叠
• 可单独验证，或在合并后明确验证

如果存在计划，应将其中的依赖图和写入范围作为主要依据。

如果没有计划，则构建等效的临时结构：

• 任务名称
• 范围
• 预期文件
• 验收标准
• 验证命令

加载 references/agent-runtime-semantics.md，了解影响并行执行成败的运行时规则。

成功标准：每个任务都能独立执行，且不存在合并竞争风险。

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

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

• 仓库技术栈
• 目标文件和目录
• 框架特定模式
• 工作属于实现还是一般支持

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

实用默认做法：

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

成功标准：每个任务都分配了合理的 Agent。

步骤 3：编写完整的 Agent 任务说明

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

• 明确的任务范围
• 任务的目的
• 需要检查的文件或目录
• 写入范围
• 必须遵循的约束和模式
• 验收标准
• 验证命令
• 明确说明该任务应编写代码还是仅进行调查

如果任务来自 DAG 计划，请保留：

• 任务 ID
• 验收标准
• 写入范围
• 验证命令
• 审核要求

如果任务涉及身份、路由、注册表或隔离敏感事项，在宣布完成前，要求任务使用 references/task-exit-gate.md。

成功标准：每条任务提示词都足够完整，新 Agent 无需询问基本问题即可开展工作。

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

在同一条助手消息中，通过多次 Agent(...) 工具调用启动每个任务分支。

编写代码的任务分支必须满足以下启动语义：

• subagent_type：匹配的 Agent 类型
• description：简短的 3–5 个词的描述
• prompt：完整的任务说明
• run_in_background: true
• isolation: "worktree"

特定运行时规则：

• 如果用户要求并行工作，不要分多条助手消息启动 Agent
• 编写代码时，为确保安全，不要依赖 Agent 的异步或隔离默认设置
• 不要在此处使用只读分支；此技能适用于全新的专业构建 Agent

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

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

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

启动后：

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

每个任务分支完成时，记录：

• 状态
• 修改的文件
• 验证结果
• 阻碍因素或偏离说明

如果某个任务分支受阻，不要将其隐去，混在汇总的成功结果中。

成功标准：每个已派生的任务分支都有可追踪的结果，且不会产生不必要的记录噪声。

第 6 步：审查、检查冲突并完成收尾

在将任务分支视为已合并之前：

• 检查已完成任务分支之间是否存在写入范围冲突
• 如果计划指定了 review 字段，则调用对应的审查技能：
  • codex → codex-review
  • claude → claude-review
  • kiro → kiro-review
• 如果任务分支来自结构化任务计划，则必须满足 references/task-exit-gate.md 的要求

如果存在冲突：

• 停止自动汇总
• 找出重叠的文件
• 有意进行合并，或升级给用户处理

成功标准：已完成的任务分支在被视为完成前，均经过审查和冲突检查。

第 7 步：报告汇总结果

总结：

• 运行了哪些任务分支
• 哪些 Agent 负责处理
• 每个任务分支的完成状态
• 修改的文件或范围
• 执行过的审查
• 尚存的阻碍因素或后续步骤安排

明确说明部分完成的情况。只有让用户看清哪些任务分支确实已完成，并行执行才算有价值。

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

注意事项

• 少于 3 个真正相互独立的任务分支时，不要使用此技能。
• 不要并行处理具有共享写入范围或依赖关系的任务。
• 不要在 SKILL.md 中内嵌庞大的 Agent 目录或启动模板。
• 不要假定全新的 Agent 了解周边任务上下文。
• 除非用户明确要求，否则不要轮询或持续读取后台 Agent 输出。
• 如果显式设置更安全，不要依赖 Agent 默认的 background 或 isolation 设置。
• 不要添加 disable-model-invocation；用户要求并行执行时，此技能应仍然可用。
• 不要添加 context: fork；此工作流协调的是全新的专业 Agent，而不是只读技能分支。
• 不要添加 paths:；这是通用的编排技能。

何时加载参考资料

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

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

• references/task-exit-gate.md 当任务来自包含验收标准、写入范围和验证要求的结构化计划时使用。

输出约定

报告：

1. 已确定的并行泳道集合
2. 每个泳道的 Agent 分配情况
3. 启动状态
4. 每个泳道的完成和审查状态
5. 冲突、阻塞项或剩余的顺序工作