Using Git Worktrees

这个 skill 解决的不是“怎么开一个新目录”，而是怎样以可复用、可回收、不会污染主工作区的方式建立隔离工作区。核心是三件事：目录选择、ignore 校验、基线验证。

何时使用

• 开始一个会修改多处文件的功能、重构或排障
• 当前工作区已经有脏改动，不适合直接继续写
• 计划让子 agent 或并行任务在独立分支中工作
• 你希望把实验性实现与主检出目录分开

不适用：

• 极小改动，且当前工作区本身已经干净、隔离收益很低
• 只是做只读研究，没有实际写代码计划
• 项目本身明确禁止使用 worktree

产物

每次使用本 skill，默认产出以下最小集合：

1. 目录决策
   • 使用哪个 worktree 根目录
   • 为什么选它
2. 安全校验结果
   • 项目内目录是否已被 ignore
   • 若未 ignore，采用了什么修正方式
3. 基线状态
   • worktree 路径、分支名
   • 采用了哪条 baseline 验证命令
   • 基线是否通过

默认要求：

• 先复用已有目录约定，再自己新建
• 对项目内 worktree 目录，先确认 ignore，再创建 worktree
• 创建后先跑一轮最小但有意义的 baseline 验证
• 如需联网安装依赖、改 .gitignore、或创建可能影响现场的分支，先判断是否需要用户确认

工作流

1. 先确认是否真的需要隔离
   • 看当前工作区是否有脏改动、是否存在并行任务、改动是否会持续一段时间
   • 如果当前工作区已经干净且任务极小，不要为了形式强行开 worktree
2. 选择 worktree 根目录
   • 按优先级检查：
     • 仓库里已有的 .worktrees/
     • 仓库里已有的 worktrees/
     • 项目文档中已经写明的目录约定，例如 AGENTS.md、README 或脚本说明
   • 若以上都没有：
     • 默认优先询问用户
     • 若当前会话需要先推进、且没有更强约束，可暂定使用 .worktrees/
3. 对项目内目录做 ignore 校验
   • 使用 git check-ignore 或等价方式确认 .worktrees/ 或 worktrees/ 已被 ignore
   • 若未被 ignore：
     • 先补 .gitignore 或项目约定的 ignore 文件
     • 不要在未 ignore 前创建 worktree
   • 对仓库外目录则不需要项目级 ignore 校验
4. 创建 worktree 和分支
   • 根据任务名称生成可读分支名
   • 避免与现有分支名、目录名冲突
   • 创建完成后进入该 worktree 再继续后续动作
5. 做最小 setup
   • 只执行当前项目明确需要的最小准备动作
   • 若项目已有现成 bootstrap 命令，优先复用
   • 不要无根据地自动下载大依赖或执行高成本初始化
6. 验证干净基线
   • 运行一条与项目相符的最小代表性验证命令
   • 例如单元测试、类型检查、构建或仓库规定的 smoke check
   • 若基线失败，先报告失败，再由用户决定是继续实现还是先修环境
7. 回报可用状态
   • 明确给出 worktree 路径、分支名、baseline 命令与结果

决策约束

• 已有目录约定优先于临时偏好
• 项目内 worktree 的 ignore 校验不能省略
• baseline 失败时，不要假装“问题不大可以先写”
• 自动化动作服从当前仓库的权限和审批模型，不默认越权执行
• 这个 skill 只解决隔离工作区，不替代计划、实现、评审或验证 skill

失败信号

• 还没确认 ignore，就先把 worktree 建出来
• 目录选址完全拍脑袋，和仓库约定冲突
• 在新 worktree 中直接开始写代码，没有任何基线验证
• 为了“方便”自动跑了重依赖安装或高成本初始化，且事前没有根据
• 基线失败却没有向用户说明，继续把后续问题混进同一个工作区

常见场景

• 需要给一个中型功能开隔离分支：
  • 先找 .worktrees/ 或 worktrees/
  • 校验 ignore
  • 建立 feature/<topic> 分支
  • 跑仓库约定的 baseline check
• 需要给并行子任务准备独立写集：
  • 为每个子任务单独建 worktree
  • 保证路径、分支与任务一一对应
  • 不共享同一个脏工作区

搭配关系

• 前置可搭配：search-first、nanospec、agent-orchestration
• 后续常搭配：实现类 skill、quality-*、finishing-a-development-branch