概览
using-git-worktrees 是什么？
using-git-worktrees 是来自 obra/superpowers 仓库的一个 workflow 技能，用来指导你为功能开发创建隔离的 Git worktrees。它统一了 worktree 的创建方式和目录位置，让你可以安全地同时在多个分支上工作，而不用在同一个工作目录里频繁切换分支。
与其手动猜测 worktree 应该放在哪里，或者冒着出现未跟踪、未忽略目录的风险，这个技能把一套清晰的目录选择和校验流程编码固化下来。目标是在保证实现工作有可靠隔离的同时，保持主项目目录干净整洁。
这个技能适合谁？
这个技能适合以下类型的开发者：
- 同时并行开发多个功能或修复
- 希望在不同项目中使用可重复的 Git worktree 约定
- 需要确保 worktree 目录位置正确，不会污染提交
- 使用命令行 Git，并且熟悉执行简单 shell 命令
它特别适合希望 Git 流程有文档、有一致性，并且希望以更安全方式快速创建临时或长期 feature 环境的团队。
using-git-worktrees 解决了哪些问题？
using-git-worktrees 帮助你在处理多个分支时避免常见问题：
- 频繁切换分支的开销： 在多个分支间并行工作，而不用不停地 stash 和 checkout。
- 项目根目录杂乱： 避免在随机位置散落临时目录和 worktree 文件夹。
- 误把 worktree 目录提交进仓库： 整个流程强调在创建 worktree 之前先验证本地 worktree 目录已被忽略。
- 不同机器上约定不一致： 通过检查现有目录以及
CLAUDE.md中的可选约定，这个技能推动你在单个项目内形成标准化的布局。
如果你经常使用 Git worktree，或者打算安全地开始使用它们，这个技能会提供一套轻量但有明确主张的操作流程。
什么时候适合使用 using-git-worktrees？
在以下场景中，你应该使用 using-git-worktrees：
- 正要开始一项需要与当前工作区隔离的功能开发。
- 准备基于既有设计或方案做实现，希望在一个干净的 worktree 中执行。
- 仓库已经在使用
.worktrees或worktrees目录，并希望继续遵循这一约定。
以下情况可能不太需要它：
- 你一次只在单个分支上工作，不需要多份工作副本。
- 你已经有严格的内部自动化工具，以不同方式管理 worktree。
在其他大多数场景下，引入 using-git-worktrees 流程都可以让你的 Git 工作流更可预期、更安全。
使用方法
安装与初始化
要把 using-git-worktrees 技能添加到你的环境中，从 obra/superpowers 仓库安装：
npx skills add https://github.com/obra/superpowers --skill using-git-worktrees
安装完成后：
- 在本地仓库检出中打开
skills/using-git-worktrees/SKILL.md文件。 - 通读一遍，了解目录选择和安全校验的具体步骤。
- 确保你当前位于一个 Git 仓库中，并且你愿意在其中创建额外的 worktree 目录。
除了 Git 和能运行技能描述中示例命令的 shell 之外，你不需要额外依赖。
核心流程：启动隔离的功能开发
当你开始一个新功能并希望使用隔离工作区时，按 using-git-worktrees 编码好的高层流程来操作：
-
“声明”你要使用的流程（给自己，也给任何助理或工具）：
"I'm using the using-git-worktrees skill to set up an isolated workspace."
-
根据目录选择流程确定 worktree 目录（见下一小节）。这样可以避免在任意路径中随意创建 worktree。
-
对选择的目录类型（项目本地 vs. 全局）执行安全校验。这是避免将 worktree 文件夹误纳入提交的关键步骤。
-
为目标分支创建 Git worktree。例如：
git worktree add <path-to-worktree> <branch-name> -
切换到新 worktree 中，在这里做实现工作；你的原始工作副本保持干净，可用于 code review、快速修复或其他任务。
每当你要启动一个不希望干扰当前工作目录的新功能、技术尝试或实验时，都可以重复这套流程。
目录选择流程
using-git-worktrees 定义了一套有序的目录选择规则，让你始终清楚 worktree 应该放在哪，而不必每次重新做决定。
1. 优先使用已有 worktree 目录
从仓库根目录开始，按优先级顺序检查是否存在推荐的 worktree 目录：
ls -d .worktrees 2>/dev/null # 首选（隐藏目录）
ls -d worktrees 2>/dev/null # 备选
- 如果存在
.worktrees，直接使用它。 - 如果没有
.worktrees但有worktrees，则使用worktrees。 - 如果两个都不存在，进入下一步。
这条规则可以让你在同一个项目内保持与先前选择的一致性。
2. 在 CLAUDE.md 中查找项目偏好
如果没有标准的 worktree 目录，检查项目根目录下 CLAUDE.md 中是否记录了偏好：
grep -i "worktree.*director" CLAUDE.md 2>/dev/null
如果 CLAUDE.md 指定了某种 worktree 目录约定，直接采用该约定，无需再额外确认。这样项目就可以集中记录其推荐的 worktree 布局方式。
3. 没有约定时，显式选择新位置
如果既不存在目录，又没有 CLAUDE.md 中的约定，就需要明确决定新 worktree 的存放位置。技能建议给自己（或团队）一个清晰的选择界面：
No worktree directory found. Where should I create worktrees?
1. .worktrees/ (project-local, hidden)
2. ~/.config/superpowers/worktrees/<project-name>/ (global location)
Which would you prefer?
- 选项 1：
.worktrees/将 worktree 放在项目旁边，默认隐藏，并且很容易在仓库内找到。 - 选项 2：
~/.config/superpowers/worktrees/<project-name>/按项目集中放在仓库根目录之外，如果你希望 Git 工作目录视觉上尽量简洁，这会比较有用。
一旦选定其中一个位置，在同一项目里就持续使用该位置，避免目录分散。
创建 worktree 前的安全校验
using-git-worktrees 特别强调安全检查，尤其是在使用位于 Git 仓库内部的项目本地目录时。
校验项目本地目录是否被忽略
对于 .worktrees 或 worktrees 这类项目本地目录，在里面创建 worktree 之前，必须先确认它们已被 Git 忽略。技能将此视为一个 必须 条件。
至少需要：
- 确认
.worktrees或worktrees出现在相关 ignore 文件中（如.gitignore、.git/info/exclude或全局 ignore 文件），并且 - 使用
git check-ignore确认在当前配置下 Git 确实忽略了该目录。
一个常见的检查模式是对目录路径执行 git check-ignore，确认 Git 在本地、全局和系统 ignore 规则的综合作用下，将其视为忽略对象。
如果目录 没有 被忽略：
- 将其添加到合适的 ignore 文件中，如果该规则应该属于仓库，则提交这条 ignore 规则；
- 然后在该位置创建任何 worktree 之前，重新执行一次检查。
这样可以大大降低你的 worktree 基础设施被误加入暂存区或提交的风险。
安全使用全局目录
如果你选择全局目录（例如 ~/.config/superpowers/worktrees/ 下），这些目录位于仓库之外，不会被 Git 跟踪。这种情况下，对 ignore 的要求就没那么关键，但仍然建议：
- 确保路径在不同机器间是稳定的（或者对团队进行文档说明）。
- 确认磁盘空间足够容纳多个完整 worktree。
持续按这套校验步骤执行，可以让你的 Git 历史专注于源码变更，而不是各种工具产物。
将技能融入你的日常工作流
using-git-worktrees 设计得很轻量，且以单个仓库为中心。要把它融入更广泛的工作流，可以：
- 在项目的贡献文档或新人引导文档中记录最终选定的 worktree 目录。
- 考虑在
CLAUDE.md中加一个短小章节，说明团队如何使用 Git worktrees。 - 如果你希望一条命令就能完成设置，可以用自己的 shell 脚本包装目录选择和安全校验步骤，同时仍然把原有规则视为“单一事实来源”。
这个技能更像是一份清晰的参考实现，你可以原样遵循，也可以在理解规则的前提下按环境做适度调整。
常见问题（FAQ）
using-git-worktrees 相比普通 Git checkout 的主要优势是什么？
using-git-worktrees 通过创建额外的工作目录（worktrees），让你可以在共享同一 Git 历史的前提下并行开发多个分支。你不用在一个目录里频繁 checkout 和 stash，每个功能或修复都可以放在独立的隔离工作区里，并配合统一的目录选择和安全流程。
如何安装 using-git-worktrees 技能？
从 obra/superpowers 仓库安装该技能：
npx skills add https://github.com/obra/superpowers --skill using-git-worktrees
安装后，在本地检出中打开 skills/using-git-worktrees/SKILL.md，按照其中的详细流程操作。
使用这个技能需要完全改变现有的 Git 流程吗？
不需要彻底推翻现有流程。using-git-worktrees 主要关注你如何启动和管理隔离的工作区。你依然可以照常 commit、rebase 和 push；这个技能只是标准化了 worktree 的创建位置和方式，并确保它们被安全地放置。
我可以在任何 Git 仓库中使用 using-git-worktrees 吗？
可以，只要该仓库本身支持 Git worktree。这个技能依赖标准的 Git 命令和常见 shell 工具。为了获得最佳效果，请从仓库根目录执行目录检查，并对任何项目本地的 worktree 目录遵循推荐的 ignore 规则。
如果我的项目已经有自己的 worktree 约定怎么办？
如果你的项目已经在使用 .worktrees、worktrees，或者在 CLAUDE.md 中记录了约定，using-git-worktrees 会通过目录选择规则自然继承这些偏好。如果你的约定完全不同，也可以只借用其中的原则（清晰的目录选择和安全检查），但指向你当前已有的目录布局。
using-git-worktrees 适合大型或长期维护的项目吗？
适合。这个技能对有多个长期分支的大型项目尤其有帮助。它强调结构化的目录选择和 ignore 规则，可以在你长期积累大量 worktree 时，仍然保持仓库结构清晰有序。
什么时候不太适合使用 using-git-worktrees？
如果你很少同时在多个分支上工作，或者团队已经在使用另一套专门的 worktree 管理工具，并强制自己的目录约定，那么 using-git-worktrees 提供的额外结构可能不足以支撑你改变已有习惯。
哪里可以查看这个技能的原始定义？
using-git-worktrees 的权威定义位于 GitHub 上 obra/superpowers 仓库中 skills/using-git-worktrees 目录里的 SKILL.md 文件。请以该文件为准，了解最精确、最新的行为说明。