メインコンテンツへスキップ
BayashiLab LogoBayashiLab(バヤシラボ)
ブログ一覧

Claude Code Worktree実践ガイド — --worktreeフラグとサブエージェント分離で実現する安全な並列開発ワークフロー

Claude Codegit worktree並列開発サブエージェント開発ワークフロー

Claude Code の worktree 機能とは何か

Claude Code を使って開発していると、「メインブランチで作業中に別の修正も並行して進めたい」という場面に出くわす。従来はブランチを切り替えるか、リポジトリをもう一つクローンするしかなかった。2026年2月、Claude Code に --worktree フラグがネイティブ実装され、この問題がスマートに解決できるようになった。

worktree とは git の機能で、ひとつのリポジトリから複数の作業ディレクトリを作成する仕組みだ。Claude Code はこれをCLIとサブエージェントの両方から簡単に扱えるようにしている。

CLI での基本的な使い方

bash
# 名前を指定して worktree を作成
claude --worktree feature-auth

# 短縮形
claude -w feature-auth

# 名前を省略するとランダム生成される
claude --worktree

実行すると <repo>/.claude/worktrees/<name>/ にフルコピーの作業ディレクトリが作られ、worktree-<name> ブランチが自動的に切られる。ベースブランチは origin/HEAD が参照される。

tmux と組み合わせれば、ターミナルを閉じても作業が続行される。

bash
claude --worktree feature-auth --tmux

忘れがちだが、.gitignore に .claude/worktrees/ を追加しておこう。

サブエージェントの worktree 分離

Claude Code の Agent ツールでサブエージェントを起動する際、isolation: "worktree" を指定すると、各エージェントが独立した worktree で作業する。

カスタムサブエージェント定義ファイル（.claude/agents/<name>.md）で指定する場合はこうなる。

yaml
---
name: refactor-module-a
description: モジュールAのリファクタリング
isolation: worktree
tools: Read, Edit, Bash, Grep, Glob
model: sonnet
---

あなたはリファクタリング専門のエージェントです。モジュールAを分析し改善してください。

CLI から JSON で渡すこともできる。

bash
claude --agents '{
  "refactorer": {
    "description": "分離されたリファクタリングエージェント",
    "prompt": "モジュールの構造を改善してください。",
    "isolation": "worktree"
  }
}'

変更がなければ worktree は自動削除され、変更があればパスとブランチ名が返される。5つ、10のエージェントを同時に走らせても、ファイルの競合は起きない。正直、最初にこれが動くのを見たときは少し感動した。

実運用でハマるリソース競合と対策

worktree はコードの分離は完璧だが、コード以外のリソースは自動では分離されない。ここが最大のハマりポイントだ。

ポート競合

2つの worktree でそれぞれ npm run dev を実行すると、両方がポート3000を取りにいく。片方がクラッシュする。worktree 作成時のフックでポート番号をオフセットするか、動的にポートを割り当てる仕組みが必要になる。

データベース競合

全 worktree がデフォルトで同じDBを参照するため、あるworktree でマイグレーションを実行すると、別の worktree が壊れる。WorktreeCreate フックで worktree ごとにDBを分離するのが確実だ。

bash
#!/bin/bash
# .claude/hooks/worktree-create.sh
WORKTREE_PATH="$1"
BRANCH_NAME="$2"

DB_SLUG=$(echo "$BRANCH_NAME" | tr '/' '-')
echo "DB_DATABASE=myapp_dev_${DB_SLUG}" >> "$WORKTREE_PATH/.env.local"
echo "DB_TEST_DATABASE=myapp_test_${DB_SLUG}" >> "$WORKTREE_PATH/.env.local"

echo "$WORKTREE_PATH"

.env ファイルが消える問題

git worktree は追跡対象ファイルだけを複製する。.env や .env.local は .gitignore に入っているため、新しい worktree には存在しない。

プロジェクトルートに .worktreeinclude を配置すれば解決する。

text
# .worktreeinclude
.env
.env.local
config/secrets.json

.gitignore 構文で、マッチしたファイルが worktree 作成時に自動コピーされる。なお、WorktreeCreate フックを定義した場合は .worktreeinclude は処理されないので注意が必要だ。

フック設定

WorktreeCreate と WorktreeRemove フックで、worktree のライフサイクルを細かく制御できる。

json
{
  "hooks": {
    "WorktreeCreate": [
      {
        "type": "command",
        "command": ".claude/hooks/worktree-create.sh",
        "timeout": 60000
      }
    ],
    "WorktreeRemove": [
      {
        "type": "command",
        "command": ".claude/hooks/worktree-cleanup.sh",
        "timeout": 30000
      }
    ]
  }
}

WorktreeCreate フックは worktree の絶対パスを標準出力に出す必要がある。これを忘れると worktree 作成が失敗する。WorktreeRemove の終了コードは無視されるため、クリーンアップの失敗でプロセスが止まることはない。

マージ戦略

worktree での作業が終わったら、PRを作るのが最もクリーンな方法だ。

bash
# worktree セッション内で
gh pr create --head worktree-feature-auth --title "Feature: 認証システム追加"

Claude Code のセッション内から「この変更でPRを作って」と頼めば、ブランチのプッシュからPR作成まで一気にやってくれる。マージ後は git worktree list で残っている worktree を確認し、不要なものを削除する。

個人的には、直接マージよりPR経由のほうがCIも回るし履歴も追いやすいので好みだ。

まとめ

Claude Code の worktree 機能は、並列開発の安全性を git レベルで担保する実用的な仕組みだ。

  • CLI: claude --worktree <name> で即座に分離環境を作成
  • サブエージェント: isolation: "worktree" で複数エージェントを安全に並列実行
  • リソース競合: .worktreeinclude とフックで .env・DB・ポートを分離
  • クリーンアップ: 変更なしなら自動削除、変更ありならブランチとパスが保持される

コードの分離は自動でやってくれるが、DB・ポート・環境変数の分離は自分で設計する必要がある。ここを押さえておけば、複数タスクの並列処理でもコンフリクトに悩まされることはなくなるだろう。

もっと読む他の技術記事も読む