Parallel worktree dev

parallel-worktree-dev

把同一个 repo 的多个 feature 拆到独立 git worktree 里同时开发。这个 skill 解决两层冲突：

• 文件层 — 两个 worktree 改同一文件，合并才暴露。通过共享 registry 显式追踪每个 worktree 改了什么，提前预警。
• 资源层 — 端口、.env、容器名、node_modules 冲突。通过自动分配端口 + 明确的 setup 步骤避免。

**不解决：**语义层（一个 AI 改了接口另一个 AI 还在调旧的）。这个只能靠人或共享 plan 文档。

何时用

直接用（并行场景）：

• 同一 repo 同时开发 ≥ 2 个独立 feature
• 多个 Claude / Codex 会话需要并行改同一个项目
• 一个 feature 卡在 review，想起新分支做别的不想 stash

主动建议（单 feature 但有隔离价值）—— AI 看到这些信号时主动提议起 worktree：

• 用户说"我要做 X"但当前 branch 有未 commit 改动 → worktree 比 stash 干净
• 用户在尝试"另一种实现方式"/重构/探索性改动 → 失败时直接弃用 worktree，不污染主分支
• feature 预期跨多个 commit / 多次迭代 / 涉及多文件 → 主分支保留可发布状态
• 用户随时可能要切回主分支处理紧急 hotfix

建议方式：一句话即可，"要不要我用 worktree 起一个隔离工作区？跑 /feat <name> 就行。" 然后照用户回答执行。不要默认强制，单个简单 bugfix / 改个常量 / 单文件小修无需 worktree。

**不用：**已经在 worktree 里 / 单文件 trivial 改动 / 用户明确说要直接改当前分支。

工作流

1) 起一个新 worktree

~/.claude/skills/parallel-worktree-dev/worktree-helper.sh start <feature-name> [base-branch]

效果：

• 在 <repo>-wt-<feature-name> 建 worktree
• 起新分支 feat/<feature-name>（base 默认是当前分支，可显式指定 main/prod/pre 等）
• 从 3100 起分配空闲端口，回显 export PORT=<n> 提示
• 注册到 ~/.claude/worktree-registry/<repo-hash>.json
• 提示需要装哪些依赖（go/node/python 自动识别）

2) 进 worktree 做事

cd <repo>-wt-<feature-name>
# 装依赖（脚本会提示具体命令）
claude   # 起独立 AI 会话

每个 worktree 的 node_modules / .venv / .env.local 都是独立的，互不影响。

3) 随时检查冲突

worktree-helper.sh list    # 各 worktree 改了多少文件
worktree-helper.sh check   # 跨 worktree 文件重叠扫描

check 会列出每两个 worktree 之间共同碰过的文件，含已 commit 和未 commit 改动。出现 OVERLAP 警告时：

• 如果是公共配置文件（go.mod, package.json）→ 串行合并，后者 rebase
• 如果是业务代码 → 协调，避免功能耦合

4) 合并前干跑

worktree-helper.sh finish <feature-name>

跑 git merge-tree 探测 rebase 是否会冲突。不会自动合，只告诉你能不能干净合 + 给出实际命令。

5) 干掉 worktree

worktree-helper.sh remove <feature-name>   # 已合好的
worktree-helper.sh prune                   # 清理外部已删的条目

Quick Reference

命令	干啥
start <name> [base]	建 worktree + 分支 + 端口 + 注册
list	看所有 active + 改动文件数
check	跨 worktree 文件重叠扫描
finish <name>	dry-run rebase 看冲突
remove <name>	删 worktree 出 registry
prune	清孤立 registry 条目

Registry 文件：~/.claude/worktree-registry/<repo-hash>.json，每个 repo 一份，所有 worktree 共享。

常见坑

• 端口冲突：脚本只分配端口号，不强制你用。dev server 要主动读 PORT env，否则各自起 3000 还是会撞。
• .env.local 不会自动拷贝：每个 worktree 独立，第一次进去要手动 cp ../<main>/.env.local .，或在脚本里加 hook。
• 数据库 migration：worktree 之间共享同一个 dev DB。两个 worktree 都跑 migration 时一定要串行，否则 schema 互相覆盖。多服务 monorepo 项目这点尤其要紧。
• node_modules 重装慢：可以 symlink 到主 repo 的，但前提是 lockfile 没动。lockfile 改了一定要本地装。
• AI 不知道彼此存在：起新 worktree 之前先 worktree-helper.sh list 看看其他在改什么；commit 前 check 一遍。
• 冲突真的发生了：默认串行合并 + rebase。如果两个都重，可以起第三个 worktree 专门做合并。

跟其他 skill 的关系

• superpowers:using-git-worktrees — 通用的 worktree 用法。本 skill 在它之上加了"跨会话 registry + 端口分配 + 冲突扫描"。需要纯粹 worktree 概念时用它，需要并行 AI 多开时用本 skill。
• superpowers:dispatching-parallel-agents — 一个 Claude 会话里并行 dispatch 多个 subagent。本 skill 是相反方向：多个独立 Claude 会话各自有完整上下文。