parallel-agents 是 rpikit 提供的一项并发智能体调度技能，用于把多个彼此独立的问题分派给多个智能体同时处理，以减少依次排查所浪费的时间。当多个问题根因不同、彼此不影响时，并行调度智能体可显著缩短总解决时间。
适用场景
适合使用并行智能体的情形包括：三个及以上测试文件因不同根因失败；多个子系统各自独立损坏；计划中互不共享状态的独立任务；跨无关文件的批量操作。
不适合使用的情形包括：失败之间可能相关（修好一个可能连带修好其他）；任务存在顺序依赖；改动之间可能冲突；任务之间存在共享状态。
决策框架
并行化之前需要确认三点：这些问题是否真正独立，即是否涉及不同文件、不同子系统，且不共享数据或状态；修复其中一个是否可能影响另一个，即是否存在共享依赖、公共配置或重叠代码路径；改动是否会发生冲突，即是否会修改同一文件、涉及相关 API 变更或相互关联的测试。只要任一答案暗示存在依赖，就应改为串行处理。
使用流程
第一步，识别独立问题，按独立性对失败或任务分组。例如 auth.test.js 的登录校验错误属于认证子系统，api.test.js 的端点路由问题属于 API 子系统，db.test.js 的连接池耗尽属于数据库子系统；三者相互独立，可以并行。
第二步，为每个智能体创建聚焦的提示词。好的提示词应只包含一个问题、包含全部必要上下文、明确预期输出，并且不依赖其他智能体。示例包括：让智能体 1 修复 auth.test.js 的登录校验错误，并限定不得修改 src/auth/ 之外的文件；让智能体 2 修复 api.test.js 的端点路由问题，并限定在 src/api/ 内；让智能体 3 修复 db.test.js 的连接池耗尽问题，并限定在 src/db/ 内；每个提示词都需说明期望行为和当前错误信息。
第三步，在单条消息中通过 Task 工具进行多次调用，并发调度这些智能体。
第四步，审查结果。逐一阅读各智能体的总结，验证其声称的修复，检查与其他智能体是否冲突，并运行受影响的测试。
第五步，整合改动。若无冲突，接受全部改动并运行完整测试套件，确认没有回归；若存在冲突，则识别冲突改动、手动解决，再运行完整测试套件并验证解决正确。
提示词要求
提示词必须具备：聚焦范围（只针对一个问题域）、自包含上下文（智能体所需全部信息）、清晰交付物（成功的标准）以及边界约束（不得触碰的内容）。应避免：范围过宽（如“修复所有测试”）、缺失上下文、交付物含糊（如“让它能跑”）、没有边界。
冲突处理
当智能体修改了重叠代码时，先识别冲突（是否同一文件、同一函数或不兼容改动），再确定优先级（哪个更正确、更符合需求、副作用更小），然后谨慎合并（兼容时取两者之长，互斥时选择其一，并测试合并结果），最后运行受影响测试、检查回归并记录解决方式。
反模式与检查清单
应避免的反模式包括：并行处理相关问题；提示词范围过宽；忽略冲突直接接受所有输出；同时调度十个以上智能体，建议保持 3 至 5 个以便管理；不给智能体设定文件边界。调度前应确认：问题已验证独立、任务间无共享状态、改动不会冲突、每个提示词聚焦且自包含、边界已指定、预期输出清晰。完成后应确认：所有结果已审查、冲突已识别并解决、完整测试套件通过、没有引入回归、改动已干净整合。