worktree-management

用途

Worktree Management 用于在 Claude Code 中借助 Git worktree 实现智能体隔离与并行任务执行。每个智能体或任务可以在自己的分支上操作，而不干扰主工作目录。

为什么使用 worktree

worktree 是同一仓库的第二（或第三、第十）个检出副本，各自位于独立分支。在独立 worktree 中工作的智能体：

不会破坏彼此进行中的修改
不共享未暂存的编辑或索引状态
任务失败时可被干净地放弃
不干扰 main（或你的功能分支）

该项目本身运行在 .claude/worktrees/<branch-name> 下的 worktree 中。

核心命令

# Create a worktree for a task branch
git worktree add .claude/worktrees/<name> -b <branch>

# List all active worktrees
git worktree list

# Remove a worktree (branch must be merged or explicitly deleted)
git worktree remove .claude/worktrees/<name>
git worktree prune   # remove stale entries

Claude Code 工具

EnterWorktree

将智能体的工作上下文切换到隔离的 worktree。后续工具调用（Read、Write、Bash 等）都在该 worktree 目录内运行。

{
  "tool": "EnterWorktree",
  "params": {
    "branch": "feat/my-task",
    "worktreePath": ".claude/worktrees/feat-my-task"
  }
}

如果分支不存在，EnterWorktree 会从当前 HEAD 创建它。如果 worktree 目录已存在，智能体会重新进入它。

ExitWorktree

将智能体返回主工作目录。始终在同一任务中与 EnterWorktree 配对使用——让 worktree 保持打开会浪费磁盘，并可能阻止 git worktree remove。

{
  "tool": "ExitWorktree"
}

隔离：自动与手动

Agent 工具的 isolation: "worktree" 参数会自动处理：

{
  "tool": "Agent",
  "params": {
    "isolation": "worktree",
    "prompt": "Implement the auth middleware changes on a clean branch."
  }
}

Claude Code 会创建 worktree，在其中运行子智能体，然后：

如果智能体未做任何修改，则清理它
返回 worktree 路径和分支名，以便你审查并合并

branch-per-worktree 模式

每个并行任务获得自己的分支：

main
├── .claude/worktrees/feat-auth-refactor    ← branch: feat/auth-refactor
├── .claude/worktrees/fix-token-expiry      ← branch: fix/token-expiry
└── .claude/worktrees/docs-update-api       ← branch: docs/update-api

以分支 slug 命名 worktree 目录。这使 git worktree list 可读，git worktree remove 明确无歧义。

并行智能体协调

将多个智能体分散到独立任务：

Orchestrator (main worktree)
  │
  ├── Agent A → worktree/feat-part-1   (writes auth.ts)
  ├── Agent B → worktree/feat-part-2   (writes middleware.ts)
  └── Agent C → worktree/docs-update   (writes README.md)
  │
  └── Orchestrator merges or PRs each branch after completion

在单次 Agent 工具调用中发送全部三个（并行启动）。编排器收集结果并决定合并顺序。

生命周期协议

创建 — EnterWorktree 或 Agent isolation: worktree 创建 worktree
工作 — 所有编辑都限定在 worktree 的分支内
提交 — 在 worktree 内提交；提交属于其分支，而非 main
退出 — ExitWorktree 或智能体自然完成
合并或 PR — 从 main 执行 git merge 或为该分支打开 PR
移除 — 合并后执行 git worktree remove + git branch -d

切勿无限期地让 worktree 保持打开。陈旧的 worktree 会累积磁盘占用并导致 git worktree prune 噪音。

安全移除检查清单

在执行 git worktree remove <path> 之前：

分支已合并（或明确放弃）
worktree 中无未暂存修改（git -C <path> status）
没有以该 worktree 为 cwd 的打开进程
创建它的智能体已退出或被停止

# Check worktree status before removal
git -C .claude/worktrees/<name> status
git worktree remove .claude/worktrees/<name>
git branch -d <branch>        # safe: refuses if unmerged
git branch -D <branch>        # force: use only if abandoning

冲突避免

worktree 共享同一个 .git 目录。两个智能体不能在不同 worktree 中检出同一分支——git 会以 fatal: '<branch>' is already checked out 拒绝。

规则：

每个 worktree 必须拥有唯一分支
智能体不应写入另一个并发智能体的 worktree 分支也会修改的文件（PR 时会产生合并冲突）
任务分解应尽量减少并行分支之间的文件重叠

何时使用 worktree 与主上下文中的子智能体

情况	使用 worktree	使用主上下文
长时间运行任务（>10 分钟）	✓
涉及多文件的任务	✓
并行独立任务	✓
快速单文件修复		✓
仅研究（只读）		✓
任务必须与父级共享上下文		✓

与 cc-orchestrate 集成

cc-orchestrate 命令对任何分散到多个实现智能体的模板使用 isolation: "worktree"。每个智能体获得自己的分支。编排器收集分支名并按顺序打开 PR 或合并。

完整的多智能体协调模式见 skills/agent-teams/SKILL.md。