claude worktree の使い方｜並列セッションと削除の手順
Claude Codeで機能追加とバグ修正を同時に進めたいのに、同じファイルを触って変更が混ざる、別セッションを開くたびに準備が増える、と悩んでいませんか。claude worktreeの意味から、始める前の確認、実際の起動、環境ファイルの扱い、作業後の統合までを順番に整理します。
claude worktreeは、Claude CodeをGitの独立した作業ディレクトリで起動する機能です。「claude --worktree <名前>」で、セッションごとにブランチとファイルを分離できます。.envの引き継ぎと終了後の扱いまで押さえれば、安全に並列開発へ導入できるとわかります。
Contents (8)
claude worktreeとは？Git worktreeとの違い
「claude worktree」と検索したときに指されているのは、多くの場合、Claude Codeの --worktree オプションです。これはGitのworktree機能を使い、Claude Codeのセッションを独立した作業ディレクトリで開始する仕組みです。
Git worktreeでは、1つのリポジトリから複数の作業ディレクトリを作れます。それぞれが別のブランチとファイルを持ちながら、Gitの履歴やリモートは共有します。つまり、機能追加用のセッションとバグ修正用のセッションを同じリポジトリで動かしても、片方の編集中ファイルがもう片方にそのまま混ざりません。
通常のGitでは git worktree add、作業ディレクトリへの移動、Claude Codeの起動、不要になったworktreeの削除を自分で行います。--worktree を使うと、この作成とセッション開始をClaude Codeがまとめて処理します。ファイルの分離が目的であり、変更内容のマージまで自動で完了する機能ではない点は覚えておきましょう。
仕様の基準はClaude Code公式ドキュメント（https://code.claude.com/docs/ja/worktrees）です。Gitの一般的な仕様はGit公式のgit-worktreeドキュメント（https://git-scm.com/docs/git-worktree）も確認できます。
使い始める前に確認する4項目
- Gitリポジトリで実行する：Claude Codeの標準worktree機能はGitリポジトリを前提にしています。対象プロジェクトで
git statusが実行でき、少なくとも基準にするコミットがある状態にします。 - 保存先を無視対象にする：リポジトリの
.gitignoreに.claude/worktrees/を追加し、自動作成されたディレクトリがメインのチェックアウトで未追跡ファイルとして表示されないようにします。 - 依存関係の準備方法を決める：worktreeは新しいチェックアウトです。
node_modules、仮想環境、ビルドキャッシュなど、Git管理外のものは共有されないため、必要なら作成後に依存関係をインストールします。 - ワークスペースの信頼を済ませる：対話形式で初めて
--worktreeを使うディレクトリでは、先に通常のclaudeを一度起動して信頼確認を済ませます。信頼が未完了だと、worktree作成前にエラーになることがあります。
claude --worktreeで起動する手順
-
メインのチェックアウトへ移動する：まず、対象リポジトリの通常の作業ディレクトリでClaude Codeを起動します。信頼確認が表示されたら内容を確認して許可します。
cd /path/to/your-repository claude -
名前を付けてworktreeを作る：別のターミナルで、作業内容が分かる名前を指定します。次の例では、Claude Codeがworktreeを作成し、その中で新しいセッションを始めます。
claude --worktree feature-authデフォルトの保存先はリポジトリ直下の
.claude/worktrees/feature-auth/、ブランチ名はworktree-feature-authです。短縮形の-wも利用できます。 -
別のタスクを別名で起動する：同じリポジトリでバグ修正も進めるなら、別ターミナルから別名を指定します。名前が異なるため、それぞれ別のディレクトリとブランチになります。
claude --worktree bugfix-123 -
名前を省略して自動命名する：名前を考えずに分離だけ使いたい場合は、引数なしで実行できます。Claude Codeが
bright-running-foxのような名前を生成します。claude --worktree -
セッション中に作成する：起動後に「worktreeで作業する」と指示して、セッションを分離する方法もあります。すでに作成したworktreeへ切り替えた場合、元のディレクトリは削除されずに残ります。
1つのworktree名を複数のターミナルで同時に使うのは避けてください。既存名の再利用は、残っているworktreeを再開する動作になるため、前回の変更やブランチ状態を確認してから実行します。
ブランチの基準と手動Gitの使い分け
標準設定では、Claude Codeはリポジトリのデフォルトブランチを示す origin/HEAD を基準に新しいworktreeを作ります。リモートがない場合や取得できない場合は、ローカルの HEAD にフォールバックします。現在のローカル作業を基準にしたい場合は、設定で次のように baseRef を head にします。
{
"worktree": {
"baseRef": "head"
}
}
初期値の fresh は、リモートのデフォルトブランチに近い新しい状態から始めたい場合に向いています。一方、まだプッシュしていないコミットを含む進行中の作業から分岐したい場合は head が候補です。任意のブランチ名を baseRef に直接指定する設定ではないため、特定の既存ブランチから始めるときはGitを直接使います。
-
新しいブランチを指定して作る：
git worktree addにパスとブランチ名を渡します。git worktree add ../project-feature-a -b feature-a -
作成先でClaude Codeを起動する：作成したディレクトリへ移動して、通常どおり
claudeを実行します。cd ../project-feature-a claude -
一覧と状態を確認する：複数のworktreeを管理するときは、パス・ブランチ・状態を一覧で確認します。
git worktree list
この方法は、既存ブランチをチェックアウトしたい場合、保存先をリポジトリ外に置きたい場合、作成と削除のタイミングを完全に管理したい場合に便利です。Pull Requestから始める場合は、公式仕様にある claude --worktree "#1234" のような指定も利用できます。
.envをworktreeへ引き継ぐ方法
新しいworktreeには、メインの作業ディレクトリにある .env や .env.local などのGit管理外ファイルは自動で入りません。起動後に「設定がない」「API接続先が未定義」となるのは、この仕組みが原因です。
プロジェクトルートに .worktreeinclude を置くと、Gitignoreの構文でコピー対象を指定できます。対象になるのは、.worktreeinclude と .gitignore の両方に一致するファイルだけです。
.env
.env.local
config/secrets.json
この設定は便利ですが、秘密情報をコピーすることになります。チームで共有する前に対象ファイルの権限、接続先、テスト用データベースの利用を確認し、本番用の認証情報を不用意に複製しないようにします。
なお、WorktreeCreate フックを設定して標準の作成処理を置き換えている場合、.worktreeinclude は処理されません。その場合はフック側で必要な設定ファイルをコピーします。詳しい仕様と例はClaude Code公式ドキュメント（https://code.claude.com/docs/ja/worktrees）の「gitignoreされたファイルをworktreeにコピーする」を参照してください。
作業後のマージと削除の手順
worktreeで行った変更は、メインブランチへ自動マージされません。変更を確認してから、通常のGit操作で取り込みます。
-
worktree内で確認する：作業ディレクトリで変更を確認し、テストを実行してからコミットします。
git status git diff git add . git commit -m "Implement authentication" -
メインのチェックアウトへ戻る：メイン側で対象ブランチを最新状態にしてから、worktreeのブランチをマージします。ブランチ名は作成時に指定した名前を使います。
cd /path/to/your-repository git switch main git merge worktree-feature-auth -
一覧で不要なworktreeを確認する：削除前に、パスとブランチを確認します。未コミットの変更や必要なファイルが残っていないか、worktree側の
git statusも確認します。git worktree list -
取り込み済みのworktreeを削除する：不要になったディレクトリと関連ブランチを削除します。
git worktree remove .claude/worktrees/feature-auth
対話形式のClaude Codeでは、変更がなく未追跡ファイルや新しいコミットもなければ、終了時にworktreeとブランチが自動削除されます。名前付きセッションや変更が残る場合は、保持するか削除するかの確認が表示されます。削除を選ぶと未コミットの変更や未追跡ファイルも失われるため、必要な成果物は先にコミットまたは退避します。
-p を使う非対話実行では終了時の確認がないため、自動クリーンアップされないことがあります。実行後は git worktree list で残存を確認し、不要なものを git worktree remove で明示的に削除してください。詳しい終了条件はAnthropicのヘルプ記事（https://support.claude.com/en/articles/14554000-claude-code-power-user-tips）にも整理されています。
よくあるエラーと対策
| 症状 | 対策 |
|---|---|
fatal: branch is already checked out と表示される |
同じブランチは複数のworktreeで同時にチェックアウトできません。新しい名前で --worktree を実行するか、不要なworktreeを確認して削除します。 |
.env や依存関係が見つからない |
新しいチェックアウトにはGit管理外のファイルがないためです。.worktreeinclude を設定し、依存関係は各worktreeで初期化します。 |
| 起動時にworktreeへ入れない | 作成先が削除されていないか、WorktreeCreate フックがパス以外の文字列を出力していないかを確認します。 |
| 変更がメイン側に見えない | 分離が正常に働いている状態です。worktreeのブランチでコミットし、メイン側でmergeまたはcherry-pickします。 |
| 2つの作業でテスト環境が奪い合いになる | worktreeが分離するのは主にファイルとブランチです。共有データベース、固定ポート、外部サービスは必要に応じて環境ごとに分けます。 |
worktreeは、同じファイルを複数セッションが同時に編集する問題を抑える仕組みです。データベースや外部サービスまで自動的に分離するものではないため、アプリケーション側の実行環境は別途設計する必要があります。
まとめ
claude worktreeを使うと、claude --worktree 名前 の短いコマンドで、Claude Codeのセッションを独立したファイルとブランチに分けられます。機能追加とバグ修正のように互いに依存しない作業は並列化しやすく、同じファイルを触る作業は統合時の競合に注意が必要です。
実運用では、次の順で進めると安全です。
.gitignoreと依存関係の準備を確認する。--worktreeに作業名を付けて起動する。.worktreeincludeで必要な環境ファイルだけを渡す。- テストとコミットを済ませてからメインブランチへマージする。
git worktree listで確認し、不要になったworktreeを削除する。
この流れを守れば、Claude Codeを複数セッションで使い分けても、作業の混線と不要なディレクトリの放置を抑えられます。