Worktree 分離

学ぶこと

Git worktrees を使うと、並列の Claude Code sessions が別々の checkout と branch を編集でき、互いのファイルに触れません。Claude Code は現在、CLI フラグ、session 内ツール、subagent 設定からこの分離をネイティブに提供します。

このセッションでは、サポートされたライフサイクルである作成、初期化、作業、再開、統合、クリーンアップを扱います。

Worktree が分離するもの

Git worktree は、独自の checkout ファイルと branch を持つ別の作業ディレクトリです。repository history と remotes はメイン checkout と共有します。

repository
├── main checkout                 branch: main
└── .claude/worktrees/feature-auth
                                  branch: worktree-feature-auth

分離境界はファイルの checkout です。外部サービス、認証情報、ports、databases、パッケージ caches、すべての Git 操作を分離するわけではありません。それらは別途調整してください。

Worktrees はエージェントの調整も行いません。委任と通信には subagents または Agent Teams を使い、ファイル編集の衝突防止に worktrees を使います。

分離 Session を開始する

--worktree または -w に名前を渡します。

claude --worktree feature-auth
# 同じ意味
claude -w feature-auth

デフォルトでは .claude/worktrees/feature-auth/ と worktree-feature-auth branch が作成されます。別のターミナルで異なる名前を使えば、もう一つの分離 session を開始できます。生成ディレクトリを ignore 規則へ追加してください。

.claude/worktrees/

既存 session で Claude に「worktree で作業して」と依頼することもできます。Claude Code はサポートされた worktree ツールで移動するため、独自のイベントストリームを再現する必要はありません。

新しい Checkout を初期化する

Worktree には tracked files がありますが、ローカルマシンの全状態はありません。そこで dependencies をインストールし、必要なローカル設定を再作成します。

Claude が作るすべての worktree に必要な gitignored files がある場合は、repository root に .worktreeinclude を置き、.gitignore 構文で指定します。

.env.local
config/dev-secrets.json

規則に一致し、すでに Git から無視されているファイルだけがコピーされます。これは利便機能であり secrets policy ではありません。機密ファイルを最小限にし、worktree を読める主体を確認してください。

カスタム Subagent を分離する

Claude に agents 用 worktrees を依頼するか、custom subagent definition に分離を組み込みます。

---
name: refactorer
description: Applies mechanical refactors across independent files
isolation: worktree
---

Apply the requested refactor, run the affected tests, and report the commit.

Claude Code はその subagent 用の一時 worktree を作成します。変更がなければ自動削除でき、変更がある場合は作業を失わずに削除できるまで残ります。

クリーンアップは状態に基づく判断

対話型 worktree session の終了時、Claude Code は changed / untracked files と新しい commits を確認します。

状態	対話型での動作
clean で無名	worktree と branch を自動削除
clean で名前付き	保持するか確認
作業を含む	保持または削除を確認
非対話 -p 実行	終了確認も自動削除も行わない

作業を含む worktree を削除すると、そのディレクトリ、branch、作業内容が削除されます。確認文を読み、対象を検証してから削除してください。

非対話実行や手動管理では Git の公開コマンドを使います。

git worktree list
git worktree remove .claude/worktrees/feature-auth
git worktree prune

uncommitted / untracked work を意図的に破棄すると決めた場合以外は、--force を付けないでください。

再開と統合

ディレクトリが存在する限り、worktree 内にいた session を再開すると同じ worktree に戻ります。--fork-session で分岐した session は Claude を起動したディレクトリから始まり、元の worktree は変更されません。

統合前に：

1. worktree 内で影響するテストを実行する
2. git status と git diff を確認する
3. 境界の明確な変更を commit する
4. 通常の Git フローで merge、cherry-pick、または PR を作成する
5. 安全に統合したか意図的に破棄した後だけ worktree を削除する

仮定してはいけないこと

• Worktrees は別々の checkouts であり、公開契約は特定のファイル複製方式を保証しません。
• ファイルシステムが clean でも、外部副作用が分離されたとは限りません。
• 対話 sessions、subagents、-p 実行では自動クリーンアップ規則が異なります。
• 非公開のディレクトリ内部構造は、安定した orchestration API ではありません。

公式情報源

• Worktrees で並列 sessions を実行する
• Claude Code CLI リファレンス

次のセッション

次は Agent SDK の公開 API を使い、Claude Code の内部実装に依存しないプログラム可能なエージェントを作ります。