如何用 Superpowers 的 Git Worktrees 实现多分支并行开发

如何用 Superpowers 的 Git Worktrees 实现多分支并行开发

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

Superpowers 是一个面向 AI 编程代理的技能框架，其中的 using-git-worktrees 技能把 Git Worktrees 的工作树隔离流程自动化：检测隔离环境、选定目录、安装依赖、跑基线测试，最后按固定格式报告工作区就绪。这套流程针对的就是多分支并行开发里最费手工的那几件事。

多分支并行的典型卡点：stash 切了又切

先说这一节要解决的问题：同时推进两三个分支时，传统的 stash 来回切为什么撑不住。

还原一个很常见的场景：主仓里正在写登录功能，线上又冒出一个要今天修的 bug，你自己还有个实验性重构不想污染当前分支。常规操作是 stash 来回切，切完回来发现依赖目录被另一个分支的配置改了，测试缓存也乱了，stash 里攒着好几个没名字的现场，每次 git checkout 都像在排雷。

Git Worktrees 给这个问题的解法是：同一个仓库只有一份 .git 对象库，但可以挂多个工作目录，每个目录钉死一个分支。你在 feature/auth 目录里动手，feature/billing 目录完全不受影响，也不必为每个分支重新 clone 一份仓库。

手工敲 git worktree add 也能做到这一点，但忽略校验、环境检测这些步骤全靠自觉。Superpowers 把整个生命周期拆成建、装、验、收四段，每段写明了判定条件和兜底动作，技能定义在 skills/using-git-worktrees/SKILL.md。下面按这四段拆开讲。

📦 建：三步完成工作树初始化

这一节解决"工作树往哪建、建之前该查什么"。

先确认自己是否已经在隔离环境里

比较 git rev-parse --git-dir 和 --git-common-dir 两个值：不相等说明你已经在 linked worktree 里，直接跳到项目设置，不要再套一层。这里有个隐蔽的坑——在 git submodule 里这两个值同样不相等，所以文档专门加了一道子模块守卫，防止把子模块误判成工作树。

第二个判断是工具优先级：如果当前代理环境自带原生工作树工具（名字通常带 Worktree 字样），优先用它。原生工具管目录放置、分支创建和清理，绕过它直接敲 git 命令会造出环境看不见的幽灵状态，这是文档里点名批评的第一号错误。

目录按三条优先级选，建前必过忽略校验

选目录的顺序：指令文件里声明过的偏好（比如 CLAUDE.md 里写死了用哪个目录）优先，其次是项目里已存在的 .worktrees/ 或 worktrees/（两个都在时隐藏目录胜出），都没有就默认在仓库根建 .worktrees/。

定下目录后有一道强制校验：确认该目录已被 .gitignore 忽略，校验命令是git check-ignore -q .worktrees（文档对 worktrees 目录也给了同样的写法）。没被忽略就先补规则并提交，再创建。这一步防的是 Git Worktrees 最经典的事故——工作树目录本身被 git 跟踪，随后把另一个分支的整棵代码树提交进了仓库。

校验通过后，核心动作一条命令：

git worktree add .worktrees/auth -b feature/auth

cd 进新目录，隔离工作区就算建好了。遇到沙箱权限拦截导致创建失败时，文档给的兜底是放弃建工作树，直接在当前目录继续走装和验。

装：依赖安装按项目文件自动适配

这一节解决"新工作树里依赖怎么装"——不靠记忆，靠文件探测。

技能按仓库根目录的标志性文件决定动作：有 package.json 跑 npm install，有 Cargo.toml 跑 cargo build，Python 项目看 requirements.txt 或 pyproject.toml 分别走 pip 或 poetry，有 go.mod 跑 go mod download。探测不到对应文件就跳过，不会硬套一条不存在的命令。

这步不能省的原因：工作树共享同一个 .git，但工作目录是全新的，node_modules、target 这类构建产物不会跟着分支走。跳过安装，后面的基线测试根本没有运行条件。

✅ 验：基线测试把关，确认工作树就绪

这一节解决"怎么判断工作区可以放心动手"。

依赖装完，立刻跑一遍项目完整的测试套件（npm test、cargo test、pytest 或 go test ./... 之类），给新工作区立一个干净基线。全绿之后按固定格式报告就绪，大致是三行："Worktree ready at ，Tests passing (47 tests, 0 failures)，Ready to implement "。

基线测试如果有失败，流程不会默认继续，而是把失败摆出来问一句：继续动手还是先查这个问题？这不是流程洁癖——基线是脏的，之后每出现一个测试失败，你都得先分辨"这是我改出来的，还是本来就坏的"，调试成本会成倍放大。

🧹 收：开发分支收尾时如何清理工作树

这一节解决"活干完了，工作树和分支怎么处置"。

收尾走 finishing-a-development-branch 技能（skills/finishing-a-development-branch/SKILL.md）。先再跑一遍全量测试——合并前的绿才是数得上的绿——然后给三个选项：本地合并回基础分支、推送并开 PR、原样保留稍后处理。走合并或明确丢弃这两条路径会触发清理：git worktree remove 删工作树，再跟一条 git worktree prune 清掉过期注册。走开 PR 则保留工作树，因为评审意见还要在这个目录里改。

清理有个边界：只处理位于 .worktrees/ 或 worktrees/ 下的工作树，宿主环境自己管理的工作区一律不碰。

⚠️ 高频踩坑：四个经典错误占了大多数

这一节把两份技能文档点名的错误合并成一张清单，都是实际流程里反复出现的。

1. 忘记校验 .gitignore。工作树目录没被忽略，内容被意外跟踪。对策就是建目录前那次 check-ignore，没通过就补规则再提交。
2. 凭肉眼判断"我肯定不在工作树里"。harness 建的隔离环境和子模块都会骗过目测，两条 rev-parse 命令跑完就有结论。
3. 基线失败还往下走。"这个测试本来就坏"不能靠猜，要么先修，要么让用户明确拍板再继续。
4. 有原生工作树工具却直接敲 git 命令。绕过工具会留下它管不了的状态，目录放哪、分支谁建、最后谁清理全部失控。

进阶：Git Worktrees 在 Superpowers 技能链里的位置

这一节回答"这套机制和哪些技能配合用"。

Git Worktrees 单独用只是省了切换时间，Superpowers 的意图是把它嵌进完整开发流：brainstorming 产出并确认设计后，进入 using-git-worktrees 准备隔离工作区；实现阶段交给 executing-plans 或 subagent-driven-development 在工作树里跑任务；最后回到 finishing-a-development-branch 做合并和清理。整条链路里，工作树在哪、基线是否干净、什么时候能删，都有明确归属。

想在自己的代理环境里试，把仓库拉到本地即可：git clone https://gitcode.com/GitHub_Trending/su/superpowers

落地后的收益是具体的：主仓不再被 stash 和频繁切换反复折腾，每个功能分支有独立的目录、依赖和测试基线，收尾时清楚该删什么、不该碰什么。建议从一个独立小功能起步，完整走一遍建、装、验、收，体会一下干净基线对"失败归因"的帮助。

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