Superpowers + Git Worktrees 完整指南：5 步建好隔离工作树，一条命令完成清理

Superpowers + Git Worktrees 完整指南：5 步建好隔离工作树，一条命令完成清理

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers

同时推进多个功能时，分支切换是最贵的一笔隐形成本：环境被污染、依赖要重装、上下文被打断。Superpowers 的 using-git-worktrees 技能把 Git Worktrees 包成一套固定的自动化流程——自动检测目录位置、验证忽略规则、按项目类型装依赖、跑基线测试——你只需要等一句三行的"工作树就绪"报告就能开工。这里拆解它的判定机制、走一遍完整流程，并附上避坑清单。

🔄 并行开发的隐形成本：分支切换到底贵在哪

真正的开销不在git checkout本身，而在它带动的环境与状态。反复切换分支通常意味着：

• 多个功能无法真正同时推进，只能轮流占用同一个工作目录
• 每个功能的依赖、构建产物互相覆盖，环境边界模糊
• 新分支要重新装依赖、重新配置，等待时间全部浪费
• 未提交的改动可能被带进另一个分支，冲突从"可能"变成"经常"

Git Worktrees 让一个仓库同时挂出多个工作目录，各自绑定一条分支，目录之间完全隔离。但原生命令只解决"目录建出来了"，不解决"环境能用起来"——依赖装没装、测试基线是不是绿的，它一概不管。Superpowers 把这整串动作固化成流程，入口在技能定义文件skills/using-git-worktrees/SKILL.md，下面先看它怎么替你做决定。

📍 目录落在哪里：工作树三级优先级与忽略规则验证

创建流程的第一个决策不是建工作树，而是确定新工作树放在哪里。Superpowers 不随机选路径，而是按固定顺序走三级判定：

1. 现有目录：检查项目里是否已经有.worktrees（隐藏目录）或worktrees目录，有就直接用；两个同时存在时，.worktrees优先。
2. 配置文件：没有现成目录时，查看CLAUDE.md等指令文件里是否声明了工作树位置偏好，声明过的直接照办。
3. 询问用户：两条线索都没有，就友好地问一次用户偏好，并把答案沿用下去。

目录定了之后不能立刻动手。还有一个必须先回答的问题：这个目录有没有被 Git 忽略？没被忽略的话，工作树里的依赖和构建产物会全部以未跟踪文件的形式出现在git status里，一次不小心的全量提交就把整棵工作树带进了仓库。所以流程里有一道硬性验证：

git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null

这条命令让 Git 自己回答"目标目录在不在忽略清单里"，返回码非零就说明没忽略。此时 Superpowers 会先把目录补进.gitignore并提交这条改动，再继续往下走——这一步拦截的是工作树内容污染仓库这个最高频的事故。

🚀 实战演练：从空目录到基线全绿的 5 步

位置与忽略规则都敲定后，创建过程本身只有 5 步。Agent 会在流程开头宣布正在使用 using-git-worktrees 技能，然后按序执行。

第 1 步：自动检测与准备

流程先回答两个问题：目录放哪、是否已被忽略。也就是上一节的三级优先级加忽略验证，已有目录通过检查就直接进入创建环节；若目录没被忽略，先补.gitignore提交再往下。

两个问题都通过后，真正落地的动作只有一条命令。

第 2 步：创建工作树

先取一下项目根目录名，后面拼路径会用到，任何时候都可以这样查看：

project=$(basename "$(git rev-parse --show-toplevel)")

接着创建工作树并切进去：

git worktree add "$path" -b "$BRANCH_NAME" cd "$path"

git worktree add会在主仓库之外生成一个独立工作目录，与主仓库共享对象库，不需要重复克隆整个仓库；cd之后，后续所有命令都发生在新工作空间里。

第 3 步：按项目类型自动装依赖

工作树建好了，但里面的代码只是"同一份代码"，每个工作树都需要自己的依赖环境。Superpowers 靠探测特征文件来决定跑什么：

if [ -f package.json ]; then npm install; fi if [ -f Cargo.toml ]; then cargo build; fi if [ -f requirements.txt ]; then pip install -r requirements.txt; fi if [ -f pyproject.toml ]; then poetry install; fi if [ -f go.mod ]; then go mod download; fi

每个分支都是"文件存在才执行"的模式：纯 Go 仓库只会触发go mod download，纯 Rust 仓库只会触发cargo build，不存在的特征文件对应的分支直接被跳过。

第 4 步：基线测试验证

依赖就绪不等于"可用"，代码本身得先能跑绿。这里对项目跑一次完整测试套件——Node.js 对应npm test，Rust 是cargo test，Python 用pytest，Go 则是go test ./...——在写任何新代码之前确立"基线"。这一步的意义在于归因：此刻若已有测试失败，说明是历史遗留问题而不是工作树引入的；跳过它，之后看到的每一次红都说不清是谁的锅。

第 5 步：报告就绪

基线确立后，最后一步是把状态收敛成固定格式的三行报告：

Worktree ready at <full-path> Tests passing (<N> tests, 0 failures) Ready to implement <feature-name>

第一行给出进入路径，第二行用测试数量确认基线干净，第三行是"可以开工"的信号。把整个过程放进一次完整会话里看，大致长这样：

用户：开始做登录模块，给我个隔离环境 Agent：using-git-worktrees 技能，准备隔离工作空间 → 项目已有 .worktrees/，忽略规则验证通过 → 创建 login 工作树，绑定 feature/login 分支 → 探测到 package.json，依赖安装完成 → 全量测试执行：47 通过，0 失败 Worktree ready at /home/lin/myproject/.worktrees/login Tests passing (47 tests, 0 failures) Ready to implement login feature

📋 场景速查：各种情形下 Agent 分别做什么

完整流程的决策分支有限，下面这张表覆盖了实际使用中最常遇到的情形，方便你快速对号入座或审计 Agent 行为：

🧹 收尾：开发完成后如何清理工作树

工作树不是建完就不管，收尾方式同样是固定的。功能做完、测试转绿之后，由 finishing-a-development-branch 技能（skills/finishing-a-development-branch/SKILL.md）接管。先用 list 确认当前分支对应哪个工作树：

git worktree list | grep $(git branch --show-current)

git worktree list会打印全部工作树及其分支的对照表，grep 过滤出当前分支所在的那一行，删哪个目录一目了然。

确认后执行删除：

git worktree remove <worktree-path>

路径参数就是上一步的输出，执行后该目录从磁盘移除，Git 侧的注册信息一并回收。这套"建—用—清"的闭环并不孤立：brainstorming 在设计获批后会自动调用它准备实现工作空间，executing-plans 和 subagent-driven-development 在工作树里执行开发任务，finishing-a-development-branch 则负责最后的收尾——四个技能串成一条流水线，全程不需要你手工管理目录。

⚠️ 避坑清单：4 个最容易犯的错

这套流程的每条规则都在拦截真实事故，以下四项可以当作自查清单，无论是自己实现类似机制，还是审查 Agent 的执行过程都适用。

1. 跳过忽略验证：工作树内容被 Git 跟踪，git status被整目录污染。流程用强制的git check-ignore检查拦截，即使目录"看起来"已被忽略也不跳过。
2. 假设目录位置：项目明明在用worktrees，你却新建了.worktrees，两套并存后维护者会混乱。始终按"现有目录 → 配置文件声明 → 询问用户"的顺序决策，不靠猜。
3. 带着失败的基线继续开发：后续每次测试红了都无法归因，分不清是新 bug 还是旧账。流程的规矩是报告失败并征求确认，而不是静默继续。
4. 硬编码环境准备命令：在 Rust 仓库上跑npm install只会立刻失败。一切以特征文件探测为前提，依赖安装命令都遵循"文件存在才执行"的模式。

📚 延伸材料：从技能源码到测试脚本

以上两个技能的文件都是纯 Markdown，想核对实现细节或扩展流程，直接读源码即可：工作空间建立流程在skills/using-git-worktrees/SKILL.md，收尾流程在skills/finishing-a-development-branch/SKILL.md。验证行为是否按预期运转，可以看技能测试入口tests/claude-code/run-skill-tests.sh，以及与子代理开发流程的集成测试tests/claude-code/test-subagent-driven-development-integration.sh。本地还没有仓库的话，先克隆一份：

git clone https://gitcode.com/GitHub_Trending/su/superpowers

克隆完成后，上面的路径在仓库根目录下可以直接定位到。

工作树解决的是"并行"，Superpowers 叠加的价值在于把准备、基线、清理这三项隐性成本变成可验证的自动动作。你不再需要记住上一个功能做到哪个分支、新目录里依赖装没装：开工前等一句绿色报告，完工后把工作树交给清理技能，仓库始终处于干净状态。

【免费下载链接】superpowersAn agentic skills framework & software development methodology that works.项目地址: https://gitcode.com/GitHub_Trending/su/superpowers