Worktree で並行作業を安全に行う

症状・対象

同じ checkout で複数セッションを動かし、未保存の変更や同じファイルを上書きしてしまう人が対象です。Git worktree で作業ディレクトリと branch を分離します。

最短解決

1. 元の checkout が Git リポジトリであることを確認する。
2. タスク名を付けて claude -w を起動する。
3. 起動先で branch と変更状態を確認してから編集する。

コピペ例

別々のターミナルから、独立した名前で起動します。

# Terminal A
claude -w feature-auth

# Terminal B
claude -w fix-login-timeout

カスタムエージェントを常に分離したい場合は、定義へ isolation: worktree を追加します。

---
name: isolated-reviewer
description: "Use when a review task needs an isolated checkout."
isolation: worktree
---

Read the requested diff, run the stated checks, and report findings.
Do not edit files unless the user explicitly requests a fix.

期待結果

• 各セッションの作業ディレクトリと branch が分かれる。
• 一方の未コミット変更が、もう一方の working tree に現れない。
• Git の履歴と remote は共有されるため、commit 後は通常の PR 手順で統合できる。

検証

各セッション内で次を実行し、パスと branch が異なることを確認します。

pwd
git status --short --branch
git worktree list

片方でテスト用ファイルを変更したとき、もう片方の git status --short にその変更が出なければ分離できています。

落とし穴

• 同じ branch を複数 worktree へ checkout しようとすると Git が拒否します。タスクごとに名前を変えます。
• worktree は Git 管理外の共有サービス、DB、ポートまでは分離しません。開発サーバーのポートやテスト DB も分けます。
• ディレクトリを直接削除すると worktree メタデータが残ります。変更を確認したうえで git worktree remove <path> を使います。
• 並列作業の担当ファイルが重なると、最終 merge では競合します。開始前に編集境界を決めます。

次の一手

• サブエージェントを並列でスポーンしてタスクを分散する — 独立性を判断して委任する
• セッションの再開と継続を活用する — セッション名と再開方法を整える