bambu-worktree

用于并行工作的隔离 worktree

在 .worktrees/<feature>/ 中创建一个新的 git worktree，并为其创建独立分支，让用户可以同时推进多个需求，而不会互相干扰（无需在同一个工作目录中不断执行 stash/checkout）。它与项目无关：不会假设默认分支名称、包管理器或分支命名约定，而是会检测或询问。

何时使用此 skill

• “为 X 创建一个 worktree。”
• “我需要并行处理 Y，不影响已经在进行的工作。”
• “将这个 feature 隔离到它自己的文件夹中。”
• “给我一个单独的 checkout 来修复 Z，同时我继续处理其他事情。”
• “为登录 feature 新建 worktree”“为这个 bug 修复设置一个并行 checkout。”
• 用户已经想好了具体分支名称，只需要准备好 worktree。

如果用户没有要求隔离，不要将它用于同一个 checkout 中的常规分支操作（git checkout -b ...）——此功能专为同时处理多项工作且互不干扰而设计。

工作流

步骤 0 — 前提条件

git rev-parse --is-inside-work-tree   # estás dentro de un repo git
git worktree list --porcelain | head -5

如果用户的消息中既没有参数，也没有需求描述，请停下来，要求用户简要描述需求（或说明想用的分支名称），再继续——你需要用它来命名文件夹和分支。

步骤 1 — 找到主仓库的根目录

所有 worktree 都应位于主仓库根目录下的 .worktrees/ 中（即 git worktree list 列出的第一个 worktree），绝不能嵌套在另一个 worktree 中。如果当前已位于某个现有 worktree 中，请用以下命令解析真实根目录：

git worktree list --porcelain | sed -n '1,/^$/p'   # el primer bloque es siempre el worktree principal

并将 .worktrees/ 相对于该根目录，而不是当前目录进行操作。

步骤 2 — 推导 feature 名称

根据用户的描述生成一个简单的 kebab-case slug：全部小写，不带重音符号，单词之间用连字符分隔，不带提交类型前缀（feat/、fix/ 等），也不带显式 scope——只保留最能唯一、清晰地标识需求的 3-6 个词。

• “为储物柜添加 PIN 登录” → agregar-login-pin-taquilla
• “修复按行程类型计算折扣” → fix-calculo-descuento-tipo-viaje
• “按销售人员统计 Excel 销售报告” → reporte-ventas-vendedor-excel

如果用户明确指定了想用的文件夹/分支名称，请原样保留（如果包含空格或大写字母，则只将其规范化为 kebab-case），不要重新解读。

步骤 3 — 检测基础分支

如果用户明确指定了基础分支，就使用该分支。如果没有，检测仓库的实际默认分支——绝不要硬编码（不要假设是 develop、main 或 master）：

git branch --show-current
gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null \
  || git remote show origin 2>/dev/null | sed -n '/HEAD branch/s/.*: //p'

1. 如果当前分支与检测到的默认分支一致，就直接将其用作基础分支，无需询问——这是开始新 feature 的常规流程。
2. 如果当前分支不同（你已经位于某个 feature branch，或另一个 worktree 中），请询问用户：要基于该分支还是默认分支创建新的 worktree——不要自行假设。

创建 worktree 之前，先运行 git fetch origin <rama-base>，确保新分支从远程最新提交创建，而不是从过时的本地副本创建。

步骤 4 — 执行前检查

• 确认 .worktrees/<feature> 尚不存在（运行 ls .worktrees/ 或 git worktree list）。如果已存在，告知用户并询问是要换个名称，还是实际上想重用/进入该 worktree。
• 确认不存在同名的本地或远程分支（运行 git branch --list <feature> / git ls-remote --heads origin <feature>）。如果存在，请告知用户并在继续前确认（它可能不属于你，也可能是一个值得继续使用的旧分支，而不是另建一个）。

第 5 步 — 确保 .worktrees/ 已被忽略

此文件夹是本地并行检出集合——绝不能推送到远程端。创建 worktree 之前，请检查目标仓库的 .gitignore：

grep -qxF '.worktrees/' .gitignore 2>/dev/null

如果没有，请将 .worktrees/ 这一行添加到该仓库的 .gitignore 中（而不是本 skills 仓库的 .gitignore），并在最终报告中明确说明——这是对已纳入版本控制的文件所做的更改，因此如果你希望先征求用户确认，请在写入前告知用户。

第 6 步 — 创建 worktree

git worktree add -b <feature> .worktrees/<feature> origin/<rama-base>

明确使用 -b <feature>（不要让 git worktree add 仅根据路径猜测分支名），以明确创建的是哪个分支。如果 origin/<rama-base> 尚未存在于本地，请在第 3 步执行 fetch 后直接使用 <rama-base>。

第 7 步 — 最终报告

向用户确认：

• 已创建的 worktree 路径（相对于主仓库根目录的 .worktrees/<feature>）。
• 新分支名称及其基于的分支。
• 如果已将 .worktrees/ 添加到 .gitignore，请明确说明。
• 建议下一个显而易见的步骤：运行 cd .worktrees/<feature> 在其中工作；如果使用 EnterWorktree 流程或新的 Claude Code 会话，也可以将该文件夹作为独立项目打开。

关键规则

1. 绝不要硬编码默认基础分支（develop/main/master）——通过 gh repo view 或 git remote show origin 检测；如果存在歧义，则询问用户。
2. 创建之前，始终检查文件夹名和分支名是否冲突（本地和远程均需检查）——绝不要覆盖或未经确认就复用。
3. 文件夹必须是主仓库根目录下的 .worktrees/（以点开头的隐藏文件夹），且必须位于目标仓库的 .gitignore 中——如果缺少，请添加并告知用户。
4. 在 git worktree add 中始终明确使用 -b <feature>——绝不要只根据路径推断分支名。
5. 如果用户已明确提供分支名或文件夹名，不要自行编造 slug——应予以保留，只规范格式。