用途
Worktree Workflow 通过 EnterWorktree / ExitWorktree 工具管理 Git worktree:在独立目录、独立分支上创建仓库的第二份检出,完成工作后再决定保留还是删除。它适合真正需要“同时存在两份检出”的场景,而不是把任何隔离性工作都交给它。
触发门槛:必须有明确指令
只有一种情况授权调用 EnterWorktree:用户请求或项目指令(CLAUDE.md / memory)中明确出现“worktree”一词。按工具自身约定,不得仅因为工作看起来隔离、有风险、实验性或并行就使用它。
若触发原因是以下情况,应改用其他方式:
- “fix this bug”或热修复,但未出现“worktree”一词:走普通 git 工作流——建分支、修复、提交。
- 调查缺陷或验证假设:在原地调查,用
git checkout -- <file>撤销。 - “在隔离环境中做这个”/“隔离实验”:普通分支或临时副本即可,隔离本身不构成 worktree 触发条件。
- 并行子代理、并行工具调用、并发任务:与 worktree 无关;如需按代理隔离仓库,应使用 Agent 工具的
isolation: "worktree"参数(另一种机制)。 - “创建分支”/“切换分支”:使用
git switch或git checkout。
在用户明确要求后,它适用于以下工作:可能被整体丢弃的高风险重构;在功能开发保留于主工作区时,为发布分支做热修复;并排比较两套实现。
工具
EnterWorktree
在新分支上创建 git worktree。仅在用户明确要求 worktree 时使用。
参数:
name(可选)——新 worktree 的描述性名称(如fix-auth-bug、experiment-caching),省略时自动生成。path(可选)——切入已有 worktree 的路径,而不是新建;与name互斥。
行为:
- 在
.claude/worktrees/<name>中创建 worktree。 - 从
origin/<default-branch>分支,而非本地 HEAD。基础引用由worktree.baseRef设置控制,默认值为fresh;head值才从本地 HEAD 分支。这是设置而非调用参数,因此未提交或未推送的本地工作默认不会带入 worktree。 - 将整个会话的工作目录切换到该 worktree——这是会话级状态,不是按任务的状态。
- 完整 git 历史可用,提交、推送等均正常。
ExitWorktree
离开 worktree 并返回原工作目录。仅对本会话中由 EnterWorktree 创建的 worktree 生效,否则为空操作,且绝不触碰手工创建或此前会话的 worktree。应在用户要求退出时调用,不要主动调用。
参数:
action(必填)——"keep"或"remove"。keep——保留 worktree 与分支在磁盘上,供后续使用。remove——删除 worktree 目录与分支。
discard_changes(可选,默认 false)——仅对remove有意义。当 worktree 存在未提交文件或未合入原分支的提交时,remove会拒绝执行并列出这些内容;只有传入discard_changes: true才继续,并永久丢弃这些工作。应把拒绝视为安全网在报告未保存的工作——覆盖前先与用户确认,不要反射性地设置它以清除错误。
工作流模式
以下模式均假定用户已明确要求在 worktree 中工作,它们本身都不构成主动调用工具的理由。
实验后合并
- 用描述性名称调用 EnterWorktree(从
origin/<default-branch>分支)。 - 实现实验性方案。
- 运行测试验证。
- 成功:提交,以 keep 退出,从主分支合并。
- 失败:提交或暂存值得保留的内容,然后以 remove 退出。若 remove 拒绝,是在报告未保存工作——应检查,而不是用 discard_changes 覆盖。
两个功能,两个分支
顺序执行而非并发——单实例规则要求先退出当前 worktree 才能创建下一个。收益是磁盘上留下两个检出,而不是两件事同时进行。
- 为功能 A 调用 EnterWorktree。
- 实现功能 A,提交。
- 以 keep 退出。
- 为功能 B 调用 EnterWorktree。
- 实现功能 B,提交。
- 以 keep 退出。
- 两个分支独立存在,就绪后合并。
A/B 比较
- 为实现 A 调用 EnterWorktree,构建、提交,以 keep 退出。
- 为实现 B 调用 EnterWorktree,构建、提交,以 keep 退出。
- 并排比较两个分支——两份检出都保留在磁盘上。
- 合并获胜者;用普通 git 命令删除失败者的分支。
缺陷调查不在此列表中。工具约定把“修复此缺陷”和“诊断此问题”路由到普通 git 工作流——在主工作目录中调查,用 git checkout -- <file> 还原。
约束
- 需要 git 仓库,或在 settings.json 中配置 WorktreeCreate / WorktreeRemove 钩子。
- 单实例:在 worktree 会话中不能再用
name创建新 worktree,须先退出;通过path切入已有 worktree 是例外。 - 会话级作用域:EnterWorktree 移动整个会话的工作目录,因此 worktree 绝不是按任务或按批次的隔离机制。
- 未提交更改或未合并提交会使 remove 拒绝,除非
discard_changes: true。 - 在 worktree 中退出会话时,会提示用户保留或删除。
何时不应使用 worktree
- 没有明确指令——用户或 CLAUDE.md / memory 都未提到“worktree”时,无论工作看起来多么隔离,都停在这里。
- 缺陷修复与功能开发——工具约定将这些交给普通 git 工作流。
- 简单分支切换——使用
git checkout或git switch。 - 单文件实验——直接编辑并用
git checkout -- file还原。 - 非 git 项目——worktree 需要 git。
最佳实践
- 用描述性名称命名 worktree:
fix-auth-timeout、experiment-redis-cache、hotfix-v2.1。 - 退出前提交或推送有意义的工作——
remove会删除本地分支,discard_changes: true会永久销毁未提交内容。 - 计划返回或合并时用
keep,一次性工作用remove——若 remove 报告未保存更改,应阅读拒绝信息,而不是强行越过。 - 在明确请求 worktree 后,可结合 experiment-loop 技能做指标驱动的迭代。
相关
- Agent 工具的
isolation: "worktree"参数——另一种机制,为单个生成的代理提供临时 git worktree(仓库的隔离副本)。这是按代理或按任务隔离所用方式;它不是 EnterWorktree,也不以用户说“worktree”为门槛。 - experiment-loop 技能——自主优化模式(可在 worktree 内运行)。
- git-workflow 技能——分支管理与提交约定。
/checkpoint命令——命名保存点(比 worktree 更轻量)。