name: orchestrating-parallel-agents description: 使用git worktrees并行生成多个AI编码代理来处理相关的GitHub问题。适用于将大型功能拆分为多个问题、使用–print标志运行并行代理或管理相关任务的基于波次的执行。 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite

协调并行代理

使用git worktrees并行生成多个Claude代理来处理相关问题。

理念

问题即提示 - 编写包含足够上下文的问题以供自主工作
最大化并行性 - 将独立工作分组为波次
快速失败 - 如果代理无法完成，则手动完成git/PR
信任但验证 - 手动审查差异，解决冲突

工作流程清单

复制并跟踪进度：

并行代理协调：
- [ ] 1. 将功能拆分为问题（每个问题涉及1-3个文件）
- [ ] 2. 组织成波次（独立 → 依赖）
- [ ] 3. 在settings.local.json中预先批准git权限
- [ ] 4. 使用--print标志生成波次
- [ ] 5. 监控进度
- [ ] 6. 手动完成滞后的任务
- [ ] 7. 合并PR（相同文件冲突时进行变基）
- [ ] 8. 清理worktrees

问题模板

每个问题应可独立完成：

## 问题
什么被破坏或缺失。

## 解决方案
高级方法。

## 要修改的文件
- `路径/到/文件` - 需要做什么更改

## 实现
代码片段或伪代码。

## 验收标准
- [ ] 可测试的结果

关键： 包含文件路径和代码示例。代理在具体起点上工作效果最佳。

波次组织

波次1：独立更改（无共享文件）
波次2：可能触及相同文件的更改（预期冲突）
波次3：集成/测试（依赖于以上所有）

规则： 相同文件的问题放在不同波次或由同一代理处理。

预先批准权限

添加到.claude/settings.local.json以启用非交互式--print模式：

"Bash(git -C /绝对/路径/到/worktree add:*)",
"Bash(git -C /绝对/路径/到/worktree commit:*)",
"Bash(git -C /绝对/路径/到/worktree push:*)"

生成代理

for issue in 101 102 103; do
  (claude --print "/worktree-issue $issue" > "issue-${issue}.log" 2>&1) &
done

监控

ps aux | grep "claude.*worktree" | wc -l  # 运行中的代理数量
git worktree list                          # 已创建的worktrees
tail -f issue-*.log                        # 实时日志

完成滞后任务

如果代理完成代码但git操作失败：

git -C <worktree> add -A
git -C <worktree> commit -m "feat: 描述"
git -C <worktree> push -u origin <分支>
gh pr create --head <分支> --title "..." --body "Closes #N"

合并冲突

gh pr merge N --squash --delete-branch

如果先前合并后出现冲突：

cd <worktree> && git fetch origin main && git rebase origin/main
# 解决冲突
git push --force-with-lease

清理

git worktree remove <路径>
git branch -D <分支>
git worktree prune

快速参考

提示	原因
每个问题1-3个文件	更高的成功率
包含“要修改的文件”	代理更快找到代码
后端优先的波次	减少前端冲突
顺序合并相同文件的PR	每次之间进行变基

问题	解决方案
代理卡在权限上	手动完成git操作
合并冲突	变基、解决、强制推送
代理偏离范围	拒绝PR，澄清问题
冲突过多	更小的波次，顺序合并