SuperAPI AI 工具集

worktree-workflow

编程与开发

查看项目

更新于 11-16 18:36

技能介绍

用途

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 中工作,它们本身都不构成主动调用工具的理由。

实验后合并

  1. 用描述性名称调用 EnterWorktree(从 origin/<default-branch> 分支)。
  2. 实现实验性方案。
  3. 运行测试验证。
  4. 成功:提交,以 keep 退出,从主分支合并。
  5. 失败:提交或暂存值得保留的内容,然后以 remove 退出。若 remove 拒绝,是在报告未保存工作——应检查,而不是用 discard_changes 覆盖。

两个功能,两个分支

顺序执行而非并发——单实例规则要求先退出当前 worktree 才能创建下一个。收益是磁盘上留下两个检出,而不是两件事同时进行。

  1. 为功能 A 调用 EnterWorktree。
  2. 实现功能 A,提交。
  3. 以 keep 退出。
  4. 为功能 B 调用 EnterWorktree。
  5. 实现功能 B,提交。
  6. 以 keep 退出。
  7. 两个分支独立存在,就绪后合并。

A/B 比较

  1. 为实现 A 调用 EnterWorktree,构建、提交,以 keep 退出。
  2. 为实现 B 调用 EnterWorktree,构建、提交,以 keep 退出。
  3. 并排比较两个分支——两份检出都保留在磁盘上。
  4. 合并获胜者;用普通 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 更轻量)。