はじめに / 対象と前提
想定読者は、Claude Code で複数タスクを並列に進めたいエンジニア。1つのリポジトリで同時に2つ以上のタスクを Claude Code に投げて、ブランチ切り替えでお互いの変更を壊し合った経験がある人向けに書く。
前提環境:
- Claude Code(2026年7月時点の CLI 版)
- Git 2.40 以降(
git worktreeが安定して使えるバージョン) - Node.js 22.x を想定したプロジェクト(
node_modulesまわりの話をするため)
git worktree 自体の一般的な使い方は解説しない。「Claude Code と組み合わせたときに何がハマるか」に絞って書く。
TL;DR
- 1つの
.gitから複数の作業ディレクトリ(worktree)を切って、そこに Claude Code を1つずつ立ち上げれば、ブランチ切り替えなしで並列にタスクを進められる - ただし
.envなどの untracked ファイルは worktree に引き継がれない → 起動直後に環境変数不足で落ちる -
node_modulesも worktree ごとに独立 → 何も考えずに並列でnpm installすると時間もディスクも食う - 開発サーバーを複数 worktree で同時に立てるとポートが衝突する
手順 / 動かし方
まず新しいタスク用の worktree を切る。
# メインの作業ディレクトリで実行
git worktree add ../myapp-feature-a -b feature-a
git worktree add ../myapp-feature-b -b feature-b
これで ../myapp-feature-a と ../myapp-feature-b という、それぞれ独立したチェックアウト先ができる。同じ .git オブジェクトDBを共有するので、コミット履歴の参照は一瞬だし、フルクローンよりディスク消費もずっと小さい。
それぞれのディレクトリで Claude Code を別セッションとして起動する。
cd ../myapp-feature-a && claude
cd ../myapp-feature-b && claude
これで2つの Claude Code セッションが、同じリポジトリの別ブランチを同時にいじれる状態になる。片方が git checkout しても、もう片方の作業ツリーには一切影響しない。
タスクが終わったら worktree を片付ける。
git worktree remove ../myapp-feature-a
git worktree prune
remove を忘れて git branch -d feature-a だけ叩くと
error: cannot delete branch 'feature-a' checked out at '/path/to/myapp-feature-a'
で弾かれる。worktree の削除が先、ブランチ削除は後、の順番を覚えておく。
ハマりどころ
1. .env が新しい worktree に無くて起動時に落ちる
git worktree add は「git が追跡しているファイル」しかチェックアウトしない。.env や .env.local は大抵 .gitignore に入っているので、新しい worktree には最初から存在しない。
Error: Missing required environment variable: DATABASE_URL
のようなエラーで気づくことが多い。回避策はシンプルで、worktree 作成直後に手元でコピーするか、シンボリックリンクを張る。
git worktree add ../myapp-feature-a -b feature-a
cp .env ../myapp-feature-a/.env
頻繁に worktree を切るなら、git worktree add の後に自動でコピーするラッパースクリプトを1本書いておくと事故が減る。
2. node_modules が worktree ごとに独立していてインストールが重複する
worktree は作業ツリーが別なので node_modules も当然別になる。同じ依存関係を worktree の数だけインストールすることになり、ディスクと時間を消費する。3並列で npm install を回すと、非力な CI ランナー程度のマシンだと数分単位で待たされることもある。
pnpm を使っているプロジェクトならグローバルストアが共有されるので npm や yarn よりは被害が小さい。npm しか使えない場合は node_modules を worktree 間でシンボリックリンクする手もあるが、依存関係のバージョンが worktree ごとに違う想定のタスク(ライブラリのメジャーアップデート検証など)ではそのまま事故る。そのケースは素直にフルインストールしたほうが安全。
3. 複数 worktree で開発サーバーを同時に立てるとポートが衝突する
npm run dev がデフォルトで 3000 番ポートを使う設定になっていると、2つ目の worktree で同じコマンドを叩いた瞬間に
Error: listen EADDRINUSE: address already in use :::3000
で落ちる。worktree ごとに PORT 環境変数を変える(先述の .env コピー時に PORT=3001 のように書き換えておく)か、dev スクリプト側をポート可変にしておく(例: next dev -p $PORT)と、Claude Code が並列にサーバーを立ち上げて動作確認するタスクでも衝突しなくなる。
背景・補足
worktree ごとに .claude/settings.local.json の権限許可リストもリセットされる(このファイル自体は大抵 gitignore 対象)。並列タスクの初回だけ Bash 実行の許可プロンプトが両方の worktree で出るのはこれが原因で、バグではない。頻繁に worktree を切る運用なら、プロジェクト共通で許可したいコマンドは gitignore 対象外の .claude/settings.json に寄せておくと、worktree をまたいでも聞かれ直さずに済む。
まとめ
- git worktree + Claude Code で、ブランチ切り替えを挟まずに複数タスクを並列で進められる
-
.envは untracked なので worktree に引き継がれない → 明示的にコピーする -
node_modulesは worktree ごとに独立 → 依存関係が同じなら pnpm やシンボリックリンクで節約できる - 開発サーバーは
PORTを worktree ごとに変えないと衝突する - 片付けは
git worktree removeが先、ブランチ削除はその後