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

编排并行代理

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

核心理念

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

工作流程清单

复制并跟踪进度：

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

Issue 模板

每个 issue 应可独立完成：

## 问题
描述什么功能损坏或缺失。

## 解决方案
高层级方法。

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

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

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

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

波次组织

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

规则： 涉及相同文件的 issues 应放在不同波次中，或由同一代理处理。

预先批准权限

在 .claude/settings.local.json 中添加以下内容，以便在非交互式 --print 模式下运行：

"Bash(git -C /absolute/path/to/worktree add:*)",
"Bash(git -C /absolute/path/to/worktree commit:*)",
"Bash(git -C /absolute/path/to/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

快速参考

技巧	原因
每个 issue 涉及 1-3 个文件	成功率更高
包含“需要修改的文件”	代理能更快找到代码
后端优先的波次	减少前端冲突
顺序合并涉及相同文件的 PRs	在每次合并之间进行 rebase

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