Claude Code の worktree：編集の衝突なしに並列セッションを動かす

Claude Code の worktree とは

git は以前から worktree に対応しています。git worktree add は、同じ .git のデータを使って、ブランチを2つ目のディレクトリにチェックアウトします。Claude Code はこれを土台にしています。--worktree（または -w）を付けると、worktree を作成し、その中でセッションを開始し、メインのチェックアウトへの編集をブロックし、終了時に後片付けを提案します。

worktree が分離するのはファイルだけです。1つの会話の中でタスクを複数の作業者に分けるならサブエージェントを使います。選択肢の比較は複数の Claude Code エージェントをご覧ください。

• 既定の場所：リポジトリルートの .claude/worktrees/<name>/。
• 既定のブランチ名：worktree-<name>。名前を省略すると、Claude Code が bright-running-fox のような名前を付けます。
• チェックアウトと共有されるもの：.git ディレクトリ（コミットやブランチはどこからでも見えます）、プロジェクトスコープのプラグイン、「今後確認しない」の権限承認。
• 共有されないもの：.env、node_modules、ビルド成果物など、gitignore されたものすべて。worktree はまっさらなチェックアウトです。

worktree のワークフローを順を追って

1. worktree フォルダを無視する

   .gitignore に .claude/worktrees/ を追加し、worktree のファイルがメインのチェックアウトで未追跡として表示されないようにします。このリポジトリで Claude をまだ一度も実行していない場合は、先に claude を1回実行してワークスペースの信頼確認を承認してください。承認するまで、対話型の --worktree 実行は終了してしまいます。

2. タスクごとにセッションを1つ始める

   タスクごとに1つのターミナルで claude --worktree <name> を実行します。既存の名前でもう一度実行すると、新しく作らずにその worktree を開き直します。セッションの途中で Claude に「worktree で作業して」と頼むこともでき、Claude は EnterWorktree ツールで自分を worktree に移します。

   # 独立した2つのセッションを、それぞれ別のターミナルで
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # プルリクエスト 1234 から worktree を作る（# は引用符で囲む）
   claude --worktree "#1234"
   
   # worktree を git status に出さない
   echo ".claude/worktrees/" >> .gitignore

3. 未追跡のファイルも持ち込む

   .env や .env.local など、プロジェクトに必要な gitignore 済みのファイルを、リポジトリルートの .worktreeinclude ファイルに .gitignore の書式で列挙します。Claude Code は、サブエージェントやデスクトップの worktree も含め、作成するすべての worktree に一致するファイルをコピーします。そのうえで worktree 内で依存関係をインストールするか、設定で準備します。この例は、今の作業から分岐し、node_modules を1つだけ使い回し、web パッケージだけをチェックアウトします。

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. セッションに作業させる

   セッションが分離されている間、Claude Code は、メインのチェックアウトを対象にしたファイル編集、メインのチェックアウトを作業ディレクトリにしたコマンド、そこへ向け直した git コマンド（git -C、--git-dir、GIT_DIR）を拒否します。ただし cp のような普通のシェルコマンドが書き込む先までは追跡しないので、権限とサンドボックスは引き続き重要です。

5. 普通のブランチと同じようにレビューしてマージする

   各 worktree は普通のブランチです。その中でコミットしてプッシュし、プルリクエストを作り、チームメンバーのものと同じようにレビューします。すべての worktree が .git を共有しているので、ブランチはメインのチェックアウトからもすぐに見えます。

6. 終了して後片付けする

   終了すると、Claude Code は worktree を確認します。名前のないセッションで変更のない worktree は、ブランチごと自動で削除されます。名前付きのセッションでは先に確認されます。変更、未追跡ファイル、新しいコミットがある場合は、worktree を残すか削除するかを尋ね、あとで戻るための claude --worktree <name> --resume コマンドを表示します。

出典：Claude Code ドキュメント、Run parallel sessions with worktrees

Claude Code の worktree 設定

いずれも設定ファイル（~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json）の worktree の下に書きます。

Claude Code の worktree、ブランチ、git worktree の違い

git worktree で手動で行う

特定の既存ブランチを使いたいときや、リポジトリの外のフォルダに置きたいときは、素の git を使います。worktree.baseRef ではブランチ名を指定できないためです。こうして作った worktree でも、Claude Code はプラグインと権限承認を共有します。

1. worktree を作り、Claude を起動し、終わったら削除する

   feature-a を新しいブランチ名に置き換えるか、-b を外して既存のブランチをチェックアウトします。

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

worktree でのサブエージェントとバックグラウンドセッション

• Claude に「エージェントには worktree を使って」と頼むか、.claude/agents/ にあるカスタムサブエージェントの frontmatter に isolation: worktree を追加すると、各サブエージェントは専用の一時的な worktree で編集します。
• 変更のないサブエージェントの worktree は、サブエージェントの終了時に削除されます。変更のあるものは、cleanupPeriodDays の経過後、作業を失わずに削除できるようになるまで定期的なクリーンアップで残されます。
• バックグラウンドセッション（claude --bg）は、既定では worktree の中だけを編集します。claude --bg --worktree で始めるか、worktree.bgIsolation を "none" に設定してください。
• デスクトップアプリでは、セッションを始める前にプロンプト欄の下にある Worktree をオンにします。

worktree の後片付けとよくある問題

• claude -p --worktree の実行には終了時の確認がないため、worktree が残ります。git worktree remove で削除してください。git がロックされていると言う場合は、先に git worktree unlock を実行します。
• Can only use --worktree in a git repository：git init を実行して最初のコミットを作るか、SVN、Perforce、Mercurial 向けに WorktreeCreate hook を設定します。
• LFS を --local でインストールしていると、Git LFS のファイルがポインタファイルとして表示されます。worktree の中で git lfs pull を実行してください。
• .claude または .claude/worktrees がシンボリックリンクの場合、Claude Code は worktree を作成しません。
• hooks の ${CLAUDE_PROJECT_DIR} はメインのチェックアウトを指したままです。worktree のパスは hook 入力の cwd フィールドから取得します。
• ベースが "fresh" で独自のコミットがない worktree や、PR がマージされた worktree は、名前を指定して開き直すと既定ブランチにリセットされます。

worktree はセッションを分け、Crewmark はセッションを働かせ続けます。

worktree で衝突の問題は解決しますが、各セッションはあなたが入力するまで待ったままです。Crewmark は、Claude Code、Codex、DeepSeek Harness、OpenCode のセッションを、職種・目標・勤務時間を持つ AI 社員に変え、ハートビートで起こしてボードから次の issue を取らせます。

1. worktree ごとに社員を1人

   各社員に専用の worktree と職種を与えます。たとえば同じリポジトリでプログラマーとレビュアーを置く構成です。複数の Claude Code エージェントもご覧ください。

2. ハートビートで仕事を始めさせる

   勤務時間中、社員は15分、30分、60分ごとに同じ会話の中で起きます。詳しくはClaude Code を能動的にする方法をご覧ください。

3. issue を割り当て、ブランチをレビューする

   ボードに仕事を置くと、各社員が issue を取り、自分のブランチにコミットし、判断が必要なときはメッセージを送ってきます。AI 社員とはもご覧ください。

Claude Code の worktree のよくある質問