using-git-worktrees

用途

该技能用于在开始需要与当前工作区隔离的功能开发，或在执行实现计划之前，创建隔离的 Git worktree。Git worktree 可创建共享同一仓库的独立工作区，从而在不切换分支的情况下同时处理多个分支。其核心原则是：系统化的目录选择 + 安全校验 = 可靠的隔离。

主要能力

• 按优先级确定 worktree 的父目录：已有 worktree 父目录 > AGENTS.md 中的偏好 > 询问用户。
• 确保项目本地目录被加入 .gitignore。
• 创建 worktree 并运行项目初始化。
• 验证干净的测试基线，确保 worktree 从干净状态开始。
• 报告 worktree 位置、测试结果与就绪状态。

使用方式

开始时需声明：“I'm using the using-git-worktrees skill to set up an isolated workspace.”

目录选择流程：

1. 检查是否存在已有的 worktree 父目录，命令示例： ls -d "../$(git rev-parse --path-format=absolute --git-common-dir | xargs dirname).worktrees" 2>/dev/null 若找到则使用该目录。
2. 检查 AGENTS.md： grep -i "worktree.*director" AGENTS.md 2>/dev/null 若指定了偏好则直接使用，不再询问。
3. 若目录不存在且 AGENTS.md 无偏好，则询问用户，提供两个选项：
   • ../$(basename "$(git rev-parse --show-toplevel)").worktrees（项目本地、隐藏）
   • ~/.locals/share/<project-name>.worktrees/（全局位置）

创建步骤：

1. 检测项目名称： project=$(git rev-parse --path-format=absolute --git-common-dir | xargs dirname)
2. 创建 worktree： path="../${project}.worktrees/${feature_name}" mkdir -p "$path" git worktree add "$path" -b "$BRANCH_NAME" cd "$path"
3. 运行项目初始化（自动检测并运行）：
   • Justfile：just setup
   • Mise：mise setup
   • Node.js：npm install / yarn install / bun install / pnpm install
   • Rust：cargo build
   • Python：pip install -r requirements.txt 或 poetry install
   • Go：go mod download
4. 验证干净的测试基线（使用项目适用的命令）：
   • Justfile：just test
   • Mise：mise check
   • npm test、cargo test、pytest、go test ./... 若测试失败：报告失败，询问是继续还是排查。 若测试通过：报告就绪。
5. 报告位置： Worktree ready at <full-path> Tests passing (<N> tests, 0 failures) Ready to implement <feature-identifier>

适用场景

• 开始需要与当前工作区隔离的功能开发。
• 执行实现计划之前。
• 由 brainstorming（第 4 阶段）在设计获批且随后进行实现时调用（必需）。
• 任何需要隔离工作区的技能。
• 与 finishing-a-development-branch 配对（工作完成后清理时必需）。
• 与 executing-plans 或 subagent-driven-development 配对，工作在该 worktree 中进行。

限制与注意事项

常见错误：

• 假设目录位置：会造成不一致、违反项目约定。修复：遵循优先级：已有 > AGENTS.md > 询问。
• 在测试失败时继续：无法区分新缺陷与既有问题。修复：报告失败，获得明确许可后再继续。
• 硬编码初始化命令：在采用不同工具的项目上会失败。修复：从项目文件（package.json 等）自动检测。

红旗（禁止事项）：

• 绝不在现有工作区内创建 worktree。
• 绝不跳过基线测试验证。
• 绝不在未询问的情况下带着失败测试继续。
• 绝不在目录不明确时假设位置。
• 绝不跳过 AGENTS.md 检查。

始终：

• 遵循目录优先级：已有 > AGENTS.md > 询问。
• 为项目本地目录验证 .gitignore。
• 自动检测并运行项目初始化。
• 验证干净的测试基线。

快速参考：

• 尚无 worktree：使用 ../<projectname>.worktrees/
• 两者都不存在：检查 AGENTS.md → 询问用户
• 目录不在 .gitignore：立即添加并提交
• 基线测试失败：报告失败并询问
• 无 package.json/Cargo.toml：跳过依赖安装

示例工作流： You: I'm using the using-git-worktrees skill to set up an isolated workspace. [Check ../<projectname>.worktrees/ - exists] [Create worktree: git worktree add ../<projectname>.worktrees/auth -b feature/auth] [Run npm install] [Run npm test - 47 passing] Worktree ready at /Users/jesse/myproject.worktrees/auth Tests passing (47 tests, 0 failures) Ready to implement auth feature