Claude Code 并行与自动化：worktree、子代理与 headless

并行的前提是隔离

想同时干两件事，先要保证它们不会互相踩脚。Claude Code 里"并行"有好几种，代价和适用场景完全不同。挑错方式，轻则白忙，重则两个会话改同一堆文件、冲突修到崩溃。

先给结论，再展开：

worktree：并行会话的正统解法

一个 git worktree 是共享仓库历史、但有自己工作目录和分支的独立检出。每个会话一个 worktree，改动就永远不会串。

claude --worktree feature-auth

默认会在仓库根目录的 .claude/worktrees/<name>/ 下创建，开一个新分支 worktree-<name>。另开一个终端换个名字，就是第二个隔离会话：

claude --worktree fix-issue-456

几条必读的规则：

• 把 .claude/worktrees/ 加进 .gitignore，否则这些目录会在主检出里显示为未跟踪文件。
• worktree 是干净检出，.env 之类的未跟踪文件不会自动带过去。要带，在项目根放一个 .worktreeinclude（.gitignore 语法，且只复制同时命中且被 gitignore 的文件）：

text .env .env.local config/secrets.json

• 退出时它会检查 worktree 里有没有未提交的改动：干净就自动删（具名会话会先问），有改动就问你留还是删。
• 想从某个 PR/MR 起头：claude --worktree "#1234"（记得加引号，# 会被 shell 当注释）。

基础分支默认是远程默认分支（worktree.baseRef: "fresh"）。如果子代理需要在你当前未推送的工作上操作，把它设成 "head"：

{
  "worktree": {
    "baseRef": "head"
  }
}

在会话内拆分：subagent 与它的 worktree

不是所有并行都要开新终端。一个"研究一下 X"的侧任务，用 subagent 更轻——它在独立上下文里跑，主会话只收摘要，工作目录共享也无所谓，因为它多半只读。

如果需要它改文件且要和其他工作并行，就让 subagent 也带 worktree。两种开法：

• 在提示里说"用 worktree 跑你的 agents"；
• 给自定义 subagent 加 frontmatter：

```markdown

name: refactorer description: 对大量文件做机械式重构 isolation: worktree

对每个受影响的文件应用指定重构，然后运行测试并汇报结果。 ```

每个 subagent 的临时 worktree 在它无改动结束时自动清理；有改动则留在磁盘上，等周期性清扫在安全时移除。

这里有个容易忽略的坑：进入 worktree 后，钩子里的 ${CLAUDE_PROJECT_DIR} 仍指向主检出，而钩子输入 JSON 里的 cwd 才是 worktree 根。写依赖路径的钩子时要用对字段。

headless：把它当成一个命令

交互式会话适合探索，流水线需要的是"输入提示、输出结果"。-p（print）模式就是干这个的：

claude -p "运行测试套件并总结失败项" \
  --permission-mode dontAsk \
  --allowedTools "Bash(npm test)" "Read"

要点：

• -p 时进程跑完就退出，适合脚本调用；
• --permission-mode dontAsk 只放行预先批准的工具，其余一律拒绝——这正是 CI 想要的语义；
• --allowedTools 精确到命令，别用宽泛的 Bash(*)；
• 需要结构化结果时用 --output-format（如 JSON/流式），方便下游程序解析。

把这两条经验记住：CI 里不要用 bypassPermissions，用 dontAsk + 精确 allowlist；需要交互式审批的动作在无人值守环境里应当被拒绝，而不是被放行。

接进代码托管平台

Claude Code 能接进 GitHub Actions 一类流水线，常见用法是响应评论里的 @claude、把 issue 转成 PR、以及自动化的 PR 审查。原则和 headless 一样：最小权限 + 明确触发。它需要有仓库读权限、评论/PR 写权限，以及对应的 API 凭据；这些在 CI 里都该走 secrets，不要硬编码。

定时任务同理：有的形态在本地会话里用调度工具反复运行一个提示（比如轮询状态），有的在云端按计划/事件触发。前者适合"本机上的周期性检查"，后者适合"仓库级、离线的例行任务"（每日代码审查、依赖审计）。别把需要你实时判断的事做成定时任务。

后台与协同

当你同时有多个会话在跑，管理它们本身成了问题：

• agent view：一屏看清每个会话在干什么、哪个在等你输入。适合"派出去几件事，隔一会儿回来收"。
• agent teams：多个 Claude 会话作为团队协同，有共享任务和会话间消息，能做集中管理。
• cross-session messaging：让你的会话之间互相传结论——比如 A 会话改了一个接口，直接通知 B 会话"你依赖的那个变了"。

这里有个判断标准：需要人和多个会话来回切，还是会话之间自己协调？ 前者用 agent view，后者用 teams / messaging。

dynamic workflow：再大一号

当一件事"超过一把子代理能搞定"的量级，比如全库审计、大迁移、或需要多路交叉验证的调研，就用 dynamic workflow——它由 Claude 写一个脚本、编排大量子代理在后台跑，最后返回一个结果。和 subagent 的区别在于谁决定下一步：subagent 是模型逐轮决定，workflow 是脚本决定。

不要为了炫技上 workflow。先问：这件事需要多路交叉验证吗？需要跑几十个并行单元吗？都不是，就用普通 subagent。

一个可复制的并行节奏

把上面的东西串成一个日常：

1. 主会话负责需要你盯着的那件事；
2. 顺手能独立完成的小事先 Esc 出去，用 claude --worktree xxx 另起一个；
3. 会话里"读一堆文件找结论"的侧任务丢给 subagent；
4. 收工时用 agent view 统一看一遍哪个卡住了、哪个等你拍板；
5. 需要长期自动跑的（每日审查）交给 CI / 定时任务，用 dontAsk + 精确权限。

小结

• 并行先隔离：会话级并行用 worktree，任务级拆分用 subagent。
• worktree 记得配 .gitignore 和 .worktreeinclude，注意 ${CLAUDE_PROJECT_DIR} 不跟着走。
• CI 用 -p + dontAsk + 精确 allowedTools，不要开 bypass。
• 多个会话用 agent view 管理，会话间协作用 teams / messaging；超大规模的编排用 dynamic workflow。

下一篇收尾：会话管理（resume / branch / rewind）、成本控制，以及我踩过和见过的那些坑。