parallel-claudes

并行 Claude 编排器

你是根编排器。用户要求你并行处理工作时，你需要管理整个生命周期：分析任务、拆分子任务、创建隔离的工作树、启动无头 Claude 子 Agent、监控其进度，并将所有内容合并回来。

先决条件

开始前，请确认以下工具均可用：

• cw — 如果缺失，请使用以下命令安装：curl -fsSL https://raw.githubusercontent.com/joyco-studio/cw/main/install.sh | bash
• claude CLI（Claude Code）
• gh CLI（GitHub CLI，基于 PR 的合并所需）

编排步骤

步骤 1：分析、拆分并选择合并策略

用户描述任务后，将其拆分为互相独立的子任务，以免产生文件冲突。每个子任务都对应一个工作树及其独立的 Claude 子 Agent。

拆分规则：

• 子任务不得修改相同文件
• 每个子任务都应自成一体，能够独立完成
• 为工作树起描述性名称（例如 feat-auth、fix-nav、add-tests）

继续之前，告知用户你的计划：列出各子任务的名称，以及每个子 Agent 将负责的工作。

开始任何工作之前，你必须询问用户要采用哪种合并策略：

• 本地合并（cw merge <name> --local）——直接将更改压缩合并到当前分支，不创建 PR。
• 通过 GitHub PR 进行远程合并（cw merge <name>）——推送分支并创建 GitHub PR 供审查。

使用 AskUserQuestion 工具提供此选项。在用户回答之前，不要继续步骤 2。

步骤 2：创建工作树

使用 Bash 工具创建所有工作树。始终使用 --no-open——否则，cw new 会进入交互式提示并无限期挂起。

cw new <name> --no-open

在一次 Bash 调用中按顺序运行所有 cw new 命令：

cw new feat-auth --no-open && cw new feat-api --no-open && cw new feat-tests --no-open

步骤 3：启动子 Agent

使用 Bash 工具，在每个工作树中启动一个无头 Claude 进程，并设置 run_in_background: true。每个子 Agent 都会自主运行，并在完成后退出。

对每个子任务，分别运行一个单独的后台 Bash 命令：

cw cd <name> && claude -p "<detailed prompt>. Commit your changes when done." --output-format text --dangerously-skip-permissions

关键规则：

• 使用 -p 标志——这会让 Claude 以非交互式（打印）模式运行。它会执行提示词，然后退出。
• 使用 --output-format text 以获得清晰的输出。
• 始终使用 --dangerously-skip-permissions——子 Agent 在隔离的工作树（一次性分支）中运行，因此需要完全自主地读取、写入和执行，而无需请求批准。若不使用此标志，子 Agent 会在终端窗口中等待权限授权而挂起。
• 始终指示子 Agent 完成后提交更改。如果没有提交，cw merge 就没有内容可合并。
• 并行启动所有子 Agent——在一条消息中分别通过后台 Bash 调用启动每个子 Agent。
• 为每个子 Agent 编写详细提示词。它们不了解更广泛的任务背景，因此要提供所需的一切信息：要构建的内容、相关代码的位置、应遵循的模式，以及任何约束条件。

步骤 4：监控进度

启动后，轮询任务是否完成：

• 使用 TaskOutput 并设置 block: false，在不阻塞的情况下检查每个后台任务。
• 使用 cw ls 查看每个工作树领先的提交数。
• 子 Agent 完成后，向用户报告进度。

步骤 5：验证提交

合并前，确认每个子 Agent 都已提交其工作。运行 cw ls，检查每个工作树显示的领先提交数 > 0。

cw ls

如果某个工作树的领先提交数为 0，说明子 Agent 未能提交。进入该工作树并手动提交：

cw cd <name> && git add -A && git commit -m "Complete <subtask description>"

在所有工作树都至少有一个提交之前，不要继续合并。

验证后，向用户提供进入各个工作树的命令，以便他们可以自行审查或继续工作：

To step into any worktree and take over:
  cw cd <name>        # enter the worktree
  claude              # start an interactive Claude session there

列出所有工作树名称，方便用户复制粘贴。然后询问用户是要继续合并，还是要手动接手。

步骤 6：合并结果

所有工作树都已验证提交后，使用用户在步骤 1 中选择的策略逐一合并：

# If user chose remote (GitHub PR)
cw merge <name>

# If user chose local (squash merge, no PR)
cw merge <name> --local

如果子任务之间存在依赖关系（例如，先执行数据库迁移，再添加 API 路由），请按正确顺序合并。

步骤 7：清理

所有合并完成后：

cw clean

cw 命令参考

命令	说明
cw new <name> --no-open	无需交互提示即可创建工作树
cw cd <name>	切换到某个工作树目录
cw ls	列出所有工作树及其分支和领先提交数
cw merge <name>	推送分支并创建 GitHub PR
cw merge <name> --local	在本地执行 Squash 合并（不创建 PR）
cw rm <name>	移除工作树及其分支
cw clean	移除所有工作树

示例

用户请求：“构建一个包含 UI、API 和数据库层的设置功能”

操作步骤：

1. 告知用户计划：拆分为 3 个并行子任务——feat-ui、feat-api、feat-db

2. 创建工作树（单次 Bash 调用）：

cw new feat-ui --no-open && cw new feat-api --no-open && cw new feat-db --no-open

3. 启动 3 个后台子 Agent（3 次并行 Bash 调用，每次都设置 run_in_background: true）：

cw cd feat-ui && claude -p "Build the settings page UI. Create components in src/components/settings/ using the existing design system in src/components/ui/. Include a form for updating user preferences with fields for: display name, email notifications toggle, and theme selector. Commit your changes when done." --output-format text --dangerously-skip-permissions

cw cd feat-api && claude -p "Create REST API routes for settings in src/api/settings/. Add GET /api/settings and PUT /api/settings endpoints. Use the existing auth middleware from src/middleware/auth.ts. Return and accept JSON matching the Settings type. Commit your changes when done." --output-format text --dangerously-skip-permissions

cw cd feat-db && claude -p "Add a settings table migration in src/db/migrations/. Columns: user_id (FK to users), display_name (text), email_notifications (boolean, default true), theme (text, default 'system'). Add the Settings model in src/db/models/. Commit your changes when done." --output-format text --dangerously-skip-permissions

4. 使用 TaskOutput（block: false）和 cw ls 监控

5. 按依赖顺序合并：

cw merge feat-db && cw merge feat-api && cw merge feat-ui

6. 清理：

cw clean

故障排除

• 找不到 cw：在 Shell 中加载它——source ~/.local/bin/cw
• cw cd 未切换目录：确保将 cw 加载为 Shell 函数，而不仅仅是脚本
• 合并冲突：在工作树中手动解决冲突并提交，然后重试 cw merge
• cw merge 拒绝执行：工作树中存在未提交的更改——子 Agent 可能尚未提交。使用 cw cd <name> 切换到该目录并手动提交
• 子 Agent 卡住或失败：通过 TaskOutput 检查其输出。如果卡住，请停止后台任务，然后使用修订后的提示词重试

参考

• 仓库：https://github.com/joyco-studio/cw