SuperAPI AI 工具集

using-git-worktrees

编程与开发

查看项目

更新于 10-25 16:16

技能介绍

该技能用于在开始需要与当前工作区隔离的功能开发,或执行实施计划之前,创建一个共享同一仓库的独立 Git worktree 工作空间。它的核心原则是:系统化的目录选择、安全检查,以及可靠的隔离。使用开始时,需要先声明“I'm using the using-git-worktrees skill to set up an isolated workspace.”

用途与目录选择

该技能按以下优先级确定 worktree 的创建位置:首先检查项目中是否已有目录,优先使用隐藏的 .worktrees,其次使用 worktrees;如果两者都存在,则 .worktrees 优先。其次,检查 CLAUDE.md 中是否通过 grep -i "worktree.*director" 指定了偏好;如果有指定,就直接采用,不再询问用户。如果既没有现成目录,也没有 CLAUDE.md 的偏好设置,就询问用户选择项目本地的 .worktrees/,还是全局位置 ~/.config/superpowers/worktrees/<project-name>/。

安全验证

对于项目本地目录(.worktrees 或 worktrees),在创建 worktree 之前,必须先用 git check-ignore 确认该目录已被忽略。如果没有被忽略,就按“立即修复损坏之处”的原则,将对应行添加到 .gitignore,提交该改动,然后再继续创建。这样做的目的是防止 worktree 内容被意外提交到仓库。全局目录位于项目之外,因此无需进行 .gitignore 验证。

创建步骤

  1. 通过 basename "$(git rev-parse --show-toplevel)" 检测项目名。
  2. 根据选定的位置拼接完整路径:项目本地路径为 $LOCATION/$BRANCH_NAME,全局路径为 ~/.config/superpowers/worktrees/$project/$BRANCH_NAME;随后执行 git worktree add "$path" -b "$BRANCH_NAME" 并进入该目录。
  3. 自动检测并运行项目初始化:如果存在 package.json,就执行 npm install;如果存在 Cargo.toml,就执行 cargo build;如果存在 requirements.txt,就执行 pip install -r requirements.txt;如果存在 pyproject.toml,就执行 poetry install;如果存在 go.mod,就执行 go mod download。
  4. 运行项目对应的测试,例如 npm test、cargo test、pytest、go test ./...,以验证基线是否干净。如果测试失败,就报告失败情况,并询问是继续还是排查问题;成功后报告就绪状态。
  5. 报告 worktree 的完整路径、测试通过数量,以及可以开始实施的功能。

适用场景与集成

该技能适合在需要并行处理多个分支、保持主工作区不受影响,或在隔离环境中执行实施计划的场景中使用。它被 brainstorming 阶段(设计获批后进入实施时必需)以及其他需要隔离工作区的技能调用,并且与完成开发分支清理的 finishing-a-development-branch 技能配合使用;实际的实施工作则在 executing-plans 或 subagent-driven-development 中发生于该 worktree 内。

限制与常见错误

技能明确列出需要避免的行为:不在验证目录已被忽略之前创建项目本地 worktree;不跳过基线测试验证;不在未询问的情况下带着失败的测试继续;不在目录位置不明确时自行假设;不跳过 CLAUDE.md 检查。同时提醒不要硬编码初始化命令,而应根据项目文件自动检测;如果项目中没有 package.json 或 Cargo.toml 等文件,就跳过依赖安装。