Claude Codeのworktreeとは？並行作業の使い方・片付け・設定と、うまく動かない時の確認

Claude Codeのworktreeとは：並行作業で編集がぶつからない仕組み

worktreeは、もともとGitにある機能です。公式のworktreeのページは、worktreeを「自分のファイルとブランチを持ち、元のフォルダと同じ履歴とリモートを共有する、別の作業フォルダ」と説明しています。同じ内容の日本語版のページもあります。

一つのフォルダで二つの会話を同時に動かすと、片方の編集がもう片方の作業中のファイルを書き換えてしまうことがあります。会話ごとにworktreeを分ければ、それぞれが自分のファイルの写しを編集するので、片方で新しい機能を作りながら、もう片方で不具合を直せます。

worktreeを使うには、Gitのリポジトリで、コミットが一つ以上あることが必要です。Git以外の仕組み（SVNなど）でも、後のフックの節で説明する方法で同じことができます。

Claude Codeのworktreeの使い方：始め方

--worktreeを付けて起動する

リポジトリのフォルダで、--worktree（短く書くと-w）と名前を付けて起動します（公式のコマンドラインの一覧にも載っています）。

claude --worktree feature-auth

この例では、リポジトリの一番上のフォルダに.claude/worktrees/feature-auth/ができ、worktree-feature-authという新しいブランチで会話が始まります。名前を省いた場合は、Claude Codeがbright-running-foxのような名前を自動で付けます。二つ目の作業を始める時は、別のターミナルで違う名前を付けて、同じように起動します。

公式ページは、.claude/worktrees/を.gitignoreに足しておくことを勧めています。足さないと、worktreeの中身が元のフォルダで「追跡されていないファイル」として見えてしまいます。

作ったworktreeで最初にやる準備

worktreeは、Gitで管理しているファイルだけを取り出した、まっさらな写しです。そのため、パッケージのインストールなど、開発の準備はworktreeの中でやり直す必要があります。Claudeに「依存パッケージを入れて」と頼むか、.claude/worktrees/の下のフォルダで自分で準備します。

.envのように、Gitで管理していないファイルも写されません。毎回写したい時は、後の.worktreeincludeの節の設定を使います。

会話の途中で「worktreeで作業して」と頼む

起動した後でも、会話の中で「worktreeで作業して」と頼めます。ClaudeはEnterWorktreeという機能でworktreeを作り、その中へ移ります。.claude/worktrees/の外にあるフォルダへ移る時は、作業場所や書き込める範囲、読み込む設定がまとめて変わるため、先に確認を求められます。この確認は、権限ルールや「don't ask again」では省けません。

途中で移った場合、フック（決めたタイミングで自動で動く仕組み）が使う${CLAUDE_PROJECT_DIR}は、会話を始めたフォルダを指したままです。worktreeの場所が必要なフックは、フックに渡されるJSONのcwdを読みます。フックの書き方はClaude Code hooksの記事で確かめられます。

プルリクエストからworktreeを作る

レビューしたいプルリクエストの番号に#を付けて渡すと、Claude Codeがその変更をoriginから取ってきて、.claude/worktrees/pr-番号にworktreeを作ります。シェルが#から後ろを無視しないように、引用符で囲みます。

claude --worktree "#1234"

GitHubのプルリクエストのURLや、GitLabのマージリクエストのURLも渡せます（GitLabはv2.1.233以降）。変更を取ってくる時にパスワードやSSH鍵のパスフレーズを聞かれる設定だと、入力を待たずに取得が失敗します。鍵をssh-agentに読み込ませ、一度手でgit fetchしてから試してください。

worktreeの片付けと、続きから再開する方法

会話を終える時の扱い

worktreeで始めた会話を終えると、Claude Codeは、消すと失われる作業が残っていないかを確かめます。

この表は、Claude CodeがGitで作ったworktreeの場合です。後で説明するフックで作ったworktreeは、フックの片付けの設定に従います。1回だけ動かすclaude -pの実行では、終える時の確認がないため、worktreeは自動では消えません。後の手で片付ける方法で消します。

残したworktreeに戻って続ける

worktreeを残して終えると、戻るためのコマンドが画面に出ます。形はclaude --worktree 名前 --resumeで、画面の幅が足りない時は-wと-rの短い形で出ます。

worktreeの中で終えた会話を--resumeや--continueで再開すると、Claude Codeはその会話をworktreeへ戻します。worktreeの会話の記録は、worktreeのフォルダに付きます。戻す前に、そのフォルダが元のフォルダとは別の作業場所のままかを確かめ、確かめられない時は戻しません。--resumeで再開する時は、終える時に出たコマンドを使うか、会話のIDや名前を付けて、リポジトリの元のフォルダ（worktreeの外）から実行するのが確実です。--continueは、起動したフォルダに記録された一番新しい会話を選ぶため、元のフォルダから実行すると目的の会話を選ばないことがあります。--fork-sessionで会話を写して始めた場合は、起動したフォルダで始まり、元の会話のworktreeには触れません。

残ったworktreeを手で片付ける

どのworktreeが残っているかは、Gitのコマンドで確かめられます。

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

まだコミットしていない変更がある時は、--forceを付けないと消せません。消す前に、残したい変更がないかを確かめてください。Claude Codeは、作業中のworktreeが片付けで消されないように鍵をかけます。そのため「鍵がかかっている（locked）」と言われて消せない時は、先にgit worktree unlockで鍵を外してください。

worktreeの作り方を変える設定

公式の設定一覧によると、この節のworktree.baseRef・symlinkDirectories・sparsePathsは、どの設定ファイルにも書ける設定キーです。最初に紹介する.worktreeincludeは、設定キーではなく、リポジトリに置くファイルです。設定ファイルの場所と優先順位は、settings.jsonの記事で確かめられます。

.envなどを写す：.worktreeinclude

リポジトリの一番上に.worktreeincludeというファイルを置くと、新しいworktreeを作るたびに、書いたファイルを元のフォルダから写します。書き方は.gitignoreと同じです。写すのは、書いた形に当てはまり、しかもGitで管理していないファイルだけです。

.env
.env.local
config/secrets.json

この設定は、--worktreeで作るworktree、サブエージェントのworktree、デスクトップアプリの並行セッションのすべてに効きます（後で説明するフックでworktreeを作る時は効かないため、フックの中で写します）。秘密の値が入ったファイルは、worktreeの数だけ写しが増える点も覚えておきます。

どこから枝分かれするかを決める：worktree.baseRef

新しいworktreeは、既定ではリモートの既定のブランチ（ふつうはmain）から枝分かれします。既定のブランチは、24時間以上取ってきていなければ最大5秒だけ取りに行き、失敗した時は手元に記録済みのものを使います。リモートが設定されていない時や、既定のブランチの記録が手元に無く取ってくることもできない時は、手元の今のHEADから始まります。手元でまだ送っていないコミットや、作業中のブランチの状態から始めたい時は、baseRefを"head"にします。

{
  "worktree": {
    "baseRef": "head"
  }
}

baseRefにブランチ名は書けません。決まったブランチから始めたい時は、Gitのgit worktree add ../project-bugfix fix-issue-456のように自分でworktreeを作り、そのフォルダの中でclaudeを起動します。

大きなリポジトリで軽くする：symlinkDirectories・sparsePaths

worktreeごとにnode_modulesのような大きなフォルダを入れ直すと、同じ中身をいくつも持つことになり、ディスクを多く使います。symlinkDirectoriesに書いたフォルダは、各worktreeで元のフォルダのものをリンク（シンボリックリンク）で使えます。リンクなので、中身はすべてのworktreeで共有されます。

{
  "worktree": {
    "symlinkDirectories": ["node_modules", ".cache"]
  }
}

たくさんのパッケージが入った大きなリポジトリでは、sparsePathsで必要なフォルダだけを取り出せます。書いたフォルダと、一番上の階層のファイルだけがworktreeに置かれます。

{
  "worktree": {
    "sparsePaths": ["packages/my-app", "shared/utils"]
  }
}

Git以外の仕組みで使う：WorktreeCreateフック

WorktreeCreateとWorktreeRemoveのフックを設定すると、worktreeを作る処理と片付ける処理を、Gitの代わりに自分のコマンドで行えます。SVNやPerforceなどを使っている時や、.claude/worktrees/以外の場所に作りたい時の方法です。WorktreeCreateのフックは、作ったフォルダのパスを出力し、Claude Codeはそこを作業場所にします。この方法では.worktreeincludeは使われないので、必要なファイルはフックの中で写します。設定の全体の例は公式ページの該当の節にあります。

デスクトップアプリでworktreeを使う

公式のデスクトップアプリのページによると、Gitのリポジトリでは、会話を始める前に、入力欄の下の行にあるプロジェクトフォルダの項目でWorktreeをオンにします。既定はオフで、オフのままだと元のフォルダで直接作業します。ローカルの会話の保存先はSettings > Claude CodeのWorktree locationで変えられ（SSHの会話は接続設定のWorktree folder）、Branch prefixを決めると、作るブランチの名前の頭に付きます。

デスクトップアプリで会話をアーカイブすると、worktreeのまだコミットしていない変更が消えることがあります。残したい変更は、アーカイブする前にコミットしておきます。追跡していないファイルだけの場合は、会話の中でClaudeが開いたプルリクエストがマージされると、聞かれずに消えることがあります。それ以外で残った変更も、ローカルの会話ではおよそ30日後にworktreeごと消えます。

サブエージェントをworktreeで動かす

サブエージェント（作業の一部を任せる別のClaude）も、それぞれ自分のworktreeで動かせます。その場で「エージェントにはworktreeを使って」と頼むか、いつも分けたい時は、.claude/agents/に置くサブエージェントのファイルにisolation: worktreeを書きます（公式のサブエージェントのページの設定項目の一つです）。

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

Apply the requested refactor across every affected file, then run the tests
and report the results.

サブエージェントのworktreeは、変更がないまま終わると自動で消えます。変更・新しいファイル・送っていないコミットが残っている間は、日数に関係なく消されません。作業が残っていないworktreeのうち、cleanupPeriodDays（既定は30日）より古いものを、定期的な片付けが消します。バックグラウンドに送った--worktreeの会話のworktreeも、この片付けの対象になります。公式のバックグラウンドの会話のページによると、agent viewやclaude --bgでバックグラウンドに始めた会話は、ファイルを編集する前に自分でworktreeへ移ります（開いていた会話を後からバックグラウンドへ送った場合は除きます）。枝分かれの元は--worktreeと同じで、baseRefが"head"でなければ既定のブランチからです。作業中の変更の続きを任せたい時は、"head"にします。

コードベース全体にわたる大きな変更なら、/batchも使えます。公式のコマンド一覧によると、変更を5〜30の独立した単位に分けて計画を出し、承認すると単位ごとにworktreeを分けたサブエージェントが動きます。サブエージェント全体の考え方はサブエージェント設計の記事、コマンドの一覧はスラッシュコマンド一覧の記事で確かめられます。

worktreeでも共有されるものと、守られる範囲

元のフォルダと共有されるもの

worktreeは自分のファイルとブランチを持ちますが、次のものは元のフォルダと共有します。

• リポジトリの.git：worktreeでのコミットも、同じ.gitに書き込まれます。
• プロジェクトに入れたプラグイン：worktreeごとに入れ直さなくても読み込まれます（v2.1.200以降）。
• 許可の記録（公式の権限設定のページ）：worktreeでBashのコマンドに「Yes, and don't ask again」を選ぶと、その許可は元のフォルダの.claude/settings.local.jsonに保存され、ほかのworktreeでも使われます（v2.1.211以降）。Windowsなど一部の環境では、そのworktreeの中だけに残ります。
• Gitで管理していないスキルなど：worktreeに.claude/skillsがない時は、元のフォルダのスキルを読み込みます。.claude/agentsと.claude/commandsも同じです（スキルはv2.1.277以降）。

元のフォルダへの書き込みを止める確認

worktreeで動いている間、Claude Codeは、元のフォルダのファイルを編集する操作、元のフォルダで動かすコマンド、git -CなどでGitの操作を元のフォルダへ向けるコマンドを止めます。コマンドの文字だけでは、Gitの操作がworktreeの中に収まるかを判断できない場合もあります。その時もClaude Codeはコマンドを止め、短いコマンドに分けて書き直すようClaudeに伝えます。

ただし、この確認は、コマンドがどのファイルに書き込むかまでは追いかけません。cpやリダイレクト（>）で元のフォルダへ書き込むコマンドは、この確認では止まらず、ふだんの権限設定とサンドボックスの設定で扱われます。worktreeは「元のフォルダを守る壁」ではなく、「並行作業の編集を分ける仕組み」と考えて、権限設定と組み合わせます。

worktreeがうまく動かない時の確認

「Failed to resolve base branch」と出て作れない

コミットが一つもないリポジトリでは、worktreeを作れません。公式のよく使う作業の流れのページは、この時にFailed to resolve base branch "HEAD": git rev-parse failedと出ると説明しています。最初のコミットをしてから、もう一度起動します。新しい版では、この時のエラーにコミットがないなどの考えられる理由も表示されるため、文言は版によって異なります。

起動するとエラーで終わってしまう

対話で起動する時は、そのフォルダを信頼済みにしておく必要があります。信頼の確認にまだ答えていないと、--worktreeはエラーで終わります。先にそのフォルダでclaudeだけを起動し、信頼の確認に答えてから使ってください（claude -pの実行は、信頼の確認を飛ばして進みます）。また、.claudeや.claude/worktrees、worktreeのフォルダ自体がシンボリックリンクになっていると、Claude Codeはworktreeを作らず、エラーにそのパスを表示します。この場合は、リンクを外してからやり直しましょう。

.envや大きなファイルが見つからない

.envのようにGitで管理していないファイルは、worktreeには写されません。.worktreeincludeに書いておきます。Git LFSをgit lfs install --localで設定している時は、worktreeの中のLFSのファイルが中身ではなく目印のファイルになります。worktreeの中でgit lfs pullを実行すると、中身を取ってこられます。

再開したら、worktreeの外で会話が始まった

worktreeのフォルダをすでに消していた時は、Claude Codeは起動したフォルダで会話を再開し、worktreeが無くなったことを画面で知らせます。「Could not re-enter your worktree」と出る時は、worktreeの中から再開しようとしていることが多いので、リポジトリの元のフォルダから再開し直します。「Refusing to use」で始まる表示は、作る時・途中で入る時・再開する時に出ることがあり、続きの文に直し方が書かれています。表示が勧める直し方に従ってください。ただし、元のフォルダ（protected checkout）の.gitを確かめられないと書かれた時は、worktreeを作り直さずに、元のフォルダ側の問題（権限など）を直します。worktreeのフォルダには作業が残っているかもしれないので、すぐには消さないでください。

終える時に、聞かれずにworktreeが消えた

v2.1.304より前は、途中でHEADを切り離したり別のブランチに切り替えたりしたworktreeを、終える時に聞かずに消してしまうことがありました。フックで作ったworktreeを、送っていないコミットがあっても聞かずに消す不具合も、v2.1.301で直っています。古い版を使っている時は、まず更新します。

まとめ：Claude Codeのworktreeは、並行作業の前に作る

Claude Codeのworktreeは、会話ごとに作業用の別フォルダとブランチを分けて、並行作業の編集がぶつからないようにする仕組みです。claude --worktree 名前で始め、終える時に残すか消すかを決め、続きは--resumeで戻ります。.envは.worktreeincludeで写し、作業中の変更から始めたい時はworktree.baseRefを"head"にします。サブエージェントはisolation: worktreeで分けられます。

大きな変更を任せる前に方針を確かめたい時はプランモードの記事、並行作業の進め方の考え方はBorisのClaude Code運用Tipsの記事も参考になります。Claude Code全体のできることや使い始め方は、Claude Codeとは？できること・料金・利用環境の選び方から読み始めてください。