parallel-worktrees

並列ワークツリー

複数の AI コーディングセッションを並行して実行します。それぞれ独自の Git ワークツリーで分離し、独自のブランチにプッシュして、独自の PR を作成します。

このスキルを使うタイミング

次の場合に有効にしてください：

• ユーザーが、2 つ以上の AI エージェントを別々の機能やバグに同時に取り組ませたい
• ユーザーがエージェントのセッションで git worktree について質問している
• ユーザーが複数のクローンを作らずに、1 つのリポジトリから並列に PR を作成したい
• ユーザーが並行するエージェント用ワークスペースのセットアップ、調整、またはクリーンアップを必要としている

判断ツリー

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 ディレクトリを共有します。二重のフェッチも、ディスクの無駄もありません。各ワークツリーでは異なるブランチをチェックアウトします。ファイルシステムレベルでは分離されていますが、オブジェクトストアは共有されます。

エージェント 1 つにつき、ワークツリー 1 つ、ブランチ 1 つ — これが基本ルールです。2 つのエージェントがワークツリーを共有すると、互いのインデックスが破損します。2 つのエージェントが同じブランチを使うと、履歴が競合します。

調整の手段としての PR — エージェントは、共有ファイルや別のワークツリーを直接読み取るのではなく、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. エージェントに作業内容を伝える

エージェントにワークスペースを明確に伝えます。

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

エージェントはこのディレクトリ内だけで作業します。他のワークツリーについて認識させる必要はありません。

3. 作業してコミットする

ワークツリー内では通常の Git フローを使います。エージェントは通常どおり git add と git commit を実行します。ブランチはメインブランチおよび他のすべてのワークツリーから分離されています。

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. メインと同期する

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

PR を開く前と、最終的にマージする前に実行してください。

6. マージしてクリーンアップする

GitHub で PR がマージされた後：

# 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

ブランチの命名

エージェントと人が担当範囲をひと目で把握できるよう、一貫したパターンを使います。

<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 エラー	同じワークツリーで 2 つのプロセスが実行されている	ワークツリー 1 つにつきエージェント 1 つにする
Detached HEAD	ブランチではなくコミット SHA から作成された	git switch -c <new-branch>
再起動後にワークツリーのパスが見つからない	ディレクトリが外部から削除された	git worktree prune を実行してから再作成する
git worktree list に古いエントリーが表示される	git worktree remove を実行せずにディレクトリが削除された	git worktree prune
エージェントがメインのチェックアウト内のファイルを編集する	エージェントの作業範囲にワークツリーのパスが指定されていない	作業ディレクトリを明示して、エージェントに再度指示する

参考資料

さらに詳しく知りたい場合は、以下を読んでください。

• 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」「parallel agents」「multiple agent sessions」に言及したとき、または AI を使って複数の機能に同時に取り組むよう依頼したときに、自動的に有効になります。