parallel-worktrees

并行工作树

并行运行多个 AI 编码会话——每个会话都在独立的 git 工作树中工作，推送到各自的分支，并创建各自的 PR。

何时使用此技能

在以下情况下启用：

• 用户想让两个或更多 AI Agent 同时处理不同的功能或 Bug
• 用户询问如何在 Agent 会话中使用 git worktree
• 用户想在同一个仓库中创建并行 PR，而不使用多个克隆
• 用户需要设置、协调或清理并发 Agent 工作区

决策树

What does the user need?

Start a new parallel session?
  → Create a worktree + branch (Lifecycle §1–2)
  → Open a terminal/agent session pointed at the worktree path
  → Brief the agent: "Work only in <worktree-path>. Branch: <branch-name>."

Push and open a PR?
  → git push -u origin <branch>
  → gh pr create (GitHub PR Sync reference)
  → Note related PRs in the description

Sync a worktree with the latest main?
  → Inside the worktree: git fetch origin && git rebase origin/main
  → Never merge across worktrees directly

Merge and clean up?
  → Merge PR on GitHub
  → git worktree remove <path> && git branch -d <branch>
  → git worktree prune

Hit an error?
  → "already checked out" → branch open elsewhere; use a new branch name
  → ".git/index.lock" → two processes on same worktree; one agent per worktree
  → Detached HEAD → git switch -c <new-branch> inside the worktree
  → Stale entry after dir deleted → git worktree prune

核心概念

工作树与克隆 — 工作树与主检出共享同一个 .git 目录。无需重复获取，也不会浪费磁盘空间。每个工作树检出不同的分支。它们在文件系统层面相互隔离，但共享同一个对象存储。

一个 Agent、一个工作树、一个分支 — 这是首要原则。两个 Agent 共用一个工作树会破坏彼此的索引。两个 Agent 使用同一个分支会产生冲突的历史记录。

以 PR 作为协调渠道 — Agent 通过 PR 标题、描述和评论传达意图，而不是通过共享文件或直接读取其他工作树。

布局约定

将工作树放在仓库根目录的同级目录中，避免 .gitignore 产生杂项：

~/projects/
  myrepo/              ← main checkout (main branch)
  myrepo-wt/           ← worktree root (sibling dir)
    feat/auth/         ← worktree for branch feat/auth
    fix/login-bug/     ← worktree for branch fix/login-bug

生命周期

1. 创建工作树

# New branch (most common)
git worktree add ../myrepo-wt/feat/auth -b feat/auth

# From an existing remote branch
git worktree add ../myrepo-wt/fix/login-bug origin/fix/login-bug

2. 向 Agent 说明任务

清楚地告知 Agent 其工作区：

Working directory: /home/user/projects/myrepo-wt/feat/auth
Branch: feat/auth
Scope: implement JWT authentication — do not touch files outside this scope

Agent 完全在此目录中操作。它不应知晓其他工作树的存在。

3. 工作并提交

在工作树中按常规 git 流程操作——Agent 按照惯例使用 git add、git commit。该分支独立于 main 分支和所有同级工作树。

4. 推送并创建 PR

git push -u origin feat/auth
gh pr create \
  --title "feat(auth): implement JWT login" \
  --body "Parallel session. Related: #<pr-number> (if any)."

有关草稿 PR、PR 模板和关联方式，请参阅 references/github-pr-sync.md。

5. 与 main 同步

# Inside the worktree
git fetch origin
git rebase origin/main   # keep history linear

在创建 PR 之前以及最终合并之前运行此操作。

6. 合并并清理

PR 在 GitHub 上合并后：

# From the main repo (not inside the worktree)
git worktree remove ../myrepo-wt/feat/auth
git branch -d feat/auth
git worktree prune          # removes stale metadata entries

分支命名

采用一致的命名模式，让 Agent（和人类）一眼就能识别归属：

<type>/<scope>/<short-description>

feat/auth/jwt-login
fix/api/null-pointer
chore/deps/upgrade-pnpm
agent/experiment/refactor-parser   ← for exploratory agent sessions

常见问题

症状	原因	解决方法
fatal: 'branch' is already checked out	该分支已在另一个工作树中打开	使用新的分支名称
.git/index.lock 错误	两个进程在同一个工作树中运行	每个工作树只分配一个 Agent
分离的 HEAD	从提交 SHA 创建，而非从分支创建	git switch -c <new-branch>
重启后工作树路径消失	目录被外部删除	运行 git worktree prune，然后重新创建
git worktree list 显示过期条目	目录被移除时未运行 git worktree remove	运行 git worktree prune
Agent 在主检出中编辑文件	Agent 未被限定在工作树路径内	重新向 Agent 说明任务，并明确指定工作目录

参考资料

需要深入了解时，请阅读以下内容：

• references/worktree-lifecycle.md — 完整命令参考、标志和边缘情况（多个工作树、裸仓库、移动工作树）
• references/github-pr-sync.md — 通过 gh CLI 创建 PR、草稿 PR、关联、状态检查和合并策略
• references/agent-coordination.md — 协调并行会话产出的模式：任务排序、交接、通过 PR 共享状态

设置与启用

npx skills add -g onsager-ai/dev-skills --skill parallel-worktrees -a claude-code -y

当用户提到“worktree”“并行 Agent”“多个 Agent 会话”，或要求使用 AI 同时处理多个功能时，会自动启用。