🛠️

複数リポジトリ × Claude Code を git worktree で統合管理する

に公開
Claude
worktree
tech

🧠 はじめに

複数リポジトリ（フロントエンド・バックエンド・インフラ）で同時並行開発する際、こんな課題に直面していませんか？

  • リポジトリ切り替えで AI の文脈がリセットされる
  • 各リポジトリで同じ feature ブランチを作るのが面倒
  • 緊急バグ修正と機能開発を並行したいが、ブランチ切り替えが煩雑
  • AI が複数リポジトリの全体構成を理解してくれない

これらの課題を、git worktree + Claude Code の --add-dir で一気に解決できます。

この記事で解説すること

  • ✅ worktree で複数ブランチを物理的に分離し、並列開発を実現
  • ✅ --add-dir で複数リポジトリ・複数 worktree を一括管理
  • ✅ settings.json で設定を永続化し、毎回の起動を効率化
  • ✅ gita で複数リポジトリの Git 操作を自動化
  • ✅ 実践的な並列開発ワークフロー

🪄 なぜ worktree × Claude Code なのか？

従来の問題：ブランチ切り替えのコスト

# 従来の開発フロー
git checkout feature/payment    # 機能開発中...
git checkout hotfix/bug-123     # 緊急バグ修正！
git checkout feature/payment    # 戻る... が、AI の文脈もリセット

問題点：

  • ブランチ切り替えのたびにワーキングディレクトリが変わる
  • AI がコンテキストを失い、再度理解に時間がかかる
  • stash や commit の強制で作業が中断される

worktree の解決策：物理的な分離

# worktree を使った並列開発
~/project/feature-payment/     # 機能開発（常時起動）
~/project/hotfix-bug-123/      # バグ修正（別ウィンドウで作業）
~/project/main/                # メインブランチ（参照用）

メリット：

  • 各ブランチが独立したディレクトリに存在
  • ブランチ切り替え不要で並列作業可能
  • Claude Code が各ブランチの文脈を独立して保持

Claude Code にとって、worktree は "セマンティックサンドボックス"
各ブランチの文脈を独立して AI が把握できる環境です。

🏗️ A. 推奨ディレクトリ構成

基本構成：複数リポジトリ + worktree

~/workspace/myproject/
 ├─ .claude/                    # 共通設定（プロジェクトスコープ）
 │   └─ settings.json           # 永続化された additionalDirectories 設定
 │
 ├─ frontend/                   # メインリポジトリ（bare or main ブランチ）
 │   └─ .git/
 ├─ frontend-feature-payment/   # worktree（feature/payment ブランチ）
 ├─ frontend-hotfix-auth/       # worktree（hotfix/auth ブランチ）
 │
 ├─ backend/                    # メインリポジトリ
 │   └─ .git/
 ├─ backend-feature-payment/    # worktree
 ├─ backend-hotfix-auth/        # worktree
 │
 └─ infra/                      # メインリポジトリ
     └─ .git/

ポイント：

  • 各リポジトリは独立した Git 管理
  • worktree は <repo>-<branch> 形式で並列配置
  • .claude/settings.json で全ディレクトリを一括管理

🔧 B. Claude Code で複数 worktree を管理する方法

方法 1：コマンドライン起動時に --add-dir を指定（一時的）

# Claude Code を起動して、複数の worktree を一括で追加
claude \
  --add-dir ~/workspace/myproject/frontend-feature-payment \
  --add-dir ~/workspace/myproject/backend-feature-payment \
  --add-dir ~/workspace/myproject/infra

メリット：

  • 一時的な作業に最適
  • 起動時に柔軟に調整可能

デメリット：

  • セッション終了後は設定が消える
  • 毎回長いコマンドを打つ必要がある

方法 2：settings.json で永続化（推奨）

プロジェクトルートに .claude/settings.json を作成し、additionalDirectories を設定：

{
  "permissions": {
    "additionalDirectories": [
      "./frontend",
      "./frontend-feature-payment",
      "./frontend-hotfix-auth",
      "./backend",
      "./backend-feature-payment",
      "./backend-hotfix-auth",
      "./infra"
    ]
  }
}

使用方法：

# プロジェクトルートから起動するだけ
cd ~/workspace/myproject
claude

# または、どこからでもプロジェクトを指定して起動
claude --project ~/workspace/myproject

メリット：

  • 設定が永続化される（毎回指定不要）
  • チームで共有可能（Git で管理すれば全員が同じ設定）
  • 相対パスで記述可能

設定ファイルのスコープ：

ファイル スコープ 用途
~/.claude/settings.json ユーザーグローバル 全プロジェクト共通の設定
.claude/settings.json プロジェクト チームで共有する設定（Git 管理）
.claude/settings.local.json プロジェクトローカル 個人的な調整（Git 無視）

方法 3：ワイルドカードパターンで動的に追加

すべての worktree を自動で追加したい場合：

{
  "permissions": {
    "additionalDirectories": [
      "./*/",           // すべてのサブディレクトリ
      "./*-feature-*/", // feature ブランチの worktree のみ
      "./*-hotfix-*/"   // hotfix ブランチの worktree のみ
    ]
  }
}

注意： ワイルドカードのサポートは Claude Code のバージョンによって異なる可能性があります。

🚀 C. 複数リポジトリの一括操作

方法 1：gita で複数リポジトリを管理（推奨）

gita は複数の Git リポジトリを一括管理できる CLI ツールです。

インストール

# pipx でインストール（推奨）
pipx install gita

# または pip でインストール
pip install gita

セットアップ

cd ~/workspace/myproject

# リポジトリをグループ化
gita group add frontend backend infra -n myproject

# グループ確認
gita group ls
# myproject: frontend, backend, infra

一括操作の例

# 全リポジトリのステータスを並べて表示
gita ll

# 全リポジトリで一括 fetch
gita fetch myproject

# 全リポジトリで一括 pull
gita pull myproject

# 全リポジトリで worktree 一括作成
gita super myproject worktree add ../$(basename $(pwd))-feature-payment -b feature/payment

# カスタムコマンドを実行
gita super myproject <任意の git コマンド>

メリット：

  • シェルスクリプト不要
  • 公開ツールで継続的にメンテナンスされる
  • グループ管理で柔軟に対応可能

方法 2：シェル関数で自動化

gita を使わない場合は、シェル関数で自動化できます。

# ~/.zshrc または ~/.bashrc に追加

# 複数リポジトリで worktree 一括作成
function multi-wt-new() {
  local branch_name=$1
  local base_branch=${2:-main}
  local repos=(frontend backend infra)

  if [ -z "$branch_name" ]; then
    echo "Usage: multi-wt-new <branch-name> [base-branch]"
    return 1
  fi

  local root_dir=$(pwd)

  for repo in "${repos[@]}"; do
    if [ ! -d "$root_dir/$repo" ]; then
      echo "⚠️  Repository not found: $repo"
      continue
    fi

    echo "📦 Creating worktree for $repo..."
    cd "$root_dir/$repo"

    # worktree 作成（リポジトリと同じ階層に配置）
    local worktree_name="${repo}-${branch_name}"
    git worktree add "../$worktree_name" -b "$branch_name" "$base_branch"

    cd "$root_dir"
  done

  echo "✅ All worktrees created for branch '$branch_name'!"
  echo "📝 Update .claude/settings.json to add new worktrees"
}

# 複数リポジトリの worktree を一括削除
function multi-wt-remove() {
  local branch_name=$1
  local repos=(frontend backend infra)

  if [ -z "$branch_name" ]; then
    echo "Usage: multi-wt-remove <branch-name>"
    return 1
  fi

  local root_dir=$(pwd)

  for repo in "${repos[@]}"; do
    if [ ! -d "$root_dir/$repo" ]; then
      continue
    fi

    echo "🧹 Removing worktree for $repo..."
    cd "$root_dir/$repo"

    local worktree_name="${repo}-${branch_name}"
    git worktree remove "../$worktree_name" 2>/dev/null
    git branch -D "$branch_name" 2>/dev/null

    cd "$root_dir"
  done

  echo "✅ All worktrees removed for branch '$branch_name'!"
}

# 全 worktree の一覧を表示
function multi-wt-list() {
  local repos=(frontend backend infra)
  local root_dir=$(pwd)

  for repo in "${repos[@]}"; do
    if [ -d "$root_dir/$repo" ]; then
      echo "📦 $repo:"
      cd "$root_dir/$repo"
      git worktree list
      cd "$root_dir"
      echo ""
    fi
  done
}

使用例

# 複数リポジトリで新機能開発開始
$ multi-wt-new feature/payment

# worktree 一覧を確認
$ multi-wt-list

# 作業完了後に一括削除
$ multi-wt-remove feature/payment

注意： worktree 作成後は .claude/settings.json の additionalDirectories を更新してください。

🧠 D. MCP でセマンティック検索を強化

MCP とは？

Model Context Protocol (MCP) は、Claude Code が外部ツールやデータソースに接続するための標準プロトコルです。複数リポジトリの横断的な理解に活用できます。

推奨 MCP サーバー

1. Serena（セマンティックコード検索）

Serena は LSP (Language Server Protocol) ベースのセマンティック検索を提供します。

主な機能：

  • find_symbol - クラス、メソッド、関数などのシンボル検索
  • find_referencing_symbols - 参照元の検索
  • search_for_pattern - パターン検索
  • get_symbols_overview - ファイルのシンボル概要

設定例（.claude/settings.json）：

{
  "mcpServers": {
    "serena": {
      "command": "npx",
      "args": ["-y", "@serena-ai/mcp-server"]
    }
  }
}

2. GitHub MCP（リポジトリ横断検索）

複数リポジトリの issue、PR、コミット履歴を横断検索できます。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

3. ローカルファイルシステム（補助的）

基本的なファイル操作用。セマンティック検索はできません。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./"]
    }
  }
}

注意： @modelcontextprotocol/server-filesystem は基本的なファイル読み書きのみで、シンボル検索やコードの意味的な理解には対応していません。セマンティック検索には Serena などの専用 MCP サーバーを使用してください。

🎯 E. 実践：並列開発ワークフロー

シナリオ：機能開発中に緊急バグ修正が発生

# 1. 現在の状況：feature/payment で開発中
~/workspace/myproject/frontend-feature-payment$ # ← ここで作業中

# 2. 緊急バグ修正の依頼が来た！
# worktree を新規作成（別のターミナルで）
cd ~/workspace/myproject
multi-wt-new hotfix/auth-bug

# 3. settings.json に追加（または自動化スクリプトで）
# .claude/settings.json に以下を追加
{
  "permissions": {
    "additionalDirectories": [
      "./frontend-feature-payment",   # 既存
      "./frontend-hotfix-auth-bug",   # 新規追加
      "./backend-feature-payment",
      "./backend-hotfix-auth-bug"
    ]
  }
}

# 4. Claude Code を起動（既存セッションがあれば /add-dir で追加）
cd ~/workspace/myproject
claude

# または、既存セッションで
/add-dir ~/workspace/myproject/frontend-hotfix-auth-bug
/add-dir ~/workspace/myproject/backend-hotfix-auth-bug

# 5. 並列作業
# ターミナル1: feature/payment で新機能開発
# ターミナル2: hotfix/auth-bug でバグ修正
# Claude Code は両方の文脈を独立して理解

# 6. バグ修正完了後、worktree 削除
multi-wt-remove hotfix/auth-bug

ワークフローのメリット

従来の方法 worktree + Claude Code
ブランチ切り替えで作業中断 並列作業で中断なし
stash や commit を強制 各ブランチで独立して作業
AI の文脈がリセット AI が各ブランチを独立理解
複数リポジトリで手動切り替え settings.json で一括管理

より効率的な並列開発のコツ

1. 常用ブランチは永続化

{
  "permissions": {
    "additionalDirectories": [
      "./frontend",              // main ブランチ（参照用）
      "./backend",
      "./infra",
      "./docs"
    ]
  }
}

2. 一時的な worktree は --add-dir で追加

# 一時的な機能開発やバグ修正
claude --add-dir ./frontend-feature-xyz --add-dir ./backend-feature-xyz

3. gita でステータスを一括確認

# すべてのリポジトリの状態を一覧表示
gita ll

# 出力例
frontend              main              ✓
frontend-feature-payment feature/payment M (2 files modified)
backend               main              ✓
backend-feature-payment  feature/payment A (1 file added)

🌍 F. まとめ

この構成で実現できること

  • ✅ 複数ブランチの並列開発（機能開発とバグ修正を同時進行）
  • ✅ 複数リポジトリの一括管理（フロントエンド・バックエンド・インフラ）
  • ✅ AI の文脈保持（各ブランチを独立して理解）
  • ✅ 設定の永続化（チーム全体で共有可能）
  • ✅ Git 操作の自動化（gita で一括操作）

推奨ツールスタック

git worktree           # ブランチの物理的分離
├─ Claude Code         # AI 駆動開発環境
│   ├─ --add-dir       # 複数ディレクトリ管理
│   └─ settings.json   # 設定の永続化
├─ gita                # 複数リポジトリの一括操作
└─ MCP                 # セマンティック検索
    ├─ Serena          # コードシンボル検索
    └─ GitHub          # リポジトリ横断検索

次のステップ

  1. gita をインストールして複数リポジトリを管理
  2. settings.json で additionalDirectories を設定して永続化
  3. MCP で Serena を追加してセマンティック検索を強化
  4. シェル関数を定義して worktree の作成・削除を自動化

Claude Code は、もはや「1 リポジトリ専用の IDE」ではありません。
git worktree + --add-dir + settings.json の組み合わせで、
複数リポジトリ・複数ブランチを横断する "開発 OS" として機能します。

🚀 G. セットアップ自動化

初期セットアップスクリプト

新しいマシンやチームメンバーのオンボーディングを簡単にするスクリプト：

#!/bin/bash
# setup-claude-worktree.sh

set -e

# 設定
PROJECT_ROOT=$(pwd)
REPOS=(frontend backend infra)

echo "🚀 Setting up Claude Code + git worktree environment..."

# 1. .claude ディレクトリ作成
mkdir -p .claude

# 2. settings.json を生成
cat > .claude/settings.json <<EOF
{
  "permissions": {
    "additionalDirectories": [
$(for repo in "${REPOS[@]}"; do
  echo "      \"./$repo\","
done | sed '$ s/,$//')
    ]
  },
  "mcpServers": {
    "serena": {
      "command": "npx",
      "args": ["-y", "@serena-ai/mcp-server"]
    }
  }
}
EOF

# 3. .gitignore に追加
if [ -f .gitignore ]; then
  grep -q "\.claude/settings\.local\.json" .gitignore || echo ".claude/settings.local.json" >> .gitignore
else
  echo ".claude/settings.local.json" > .gitignore
fi

# 4. gita でリポジトリをグループ化
if command -v gita &> /dev/null; then
  PROJECT_NAME=$(basename "$PROJECT_ROOT")
  gita group add "${REPOS[@]}" -n "$PROJECT_NAME"
  echo "✅ gita group created: $PROJECT_NAME"
else
  echo "⚠️  gita not found. Install with: pipx install gita"
fi

echo ""
echo "✅ Setup completed!"
echo ""
echo "📝 Next steps:"
echo "  1. cd $PROJECT_ROOT"
echo "  2. claude"
echo ""
echo "📚 Create worktree:"
echo "  multi-wt-new feature/your-feature"

使用方法

# 1. プロジェクトルートで実行
cd ~/workspace/myproject
chmod +x setup-claude-worktree.sh
./setup-claude-worktree.sh

# 2. Claude Code を起動
claude

# 3. worktree を作成
multi-wt-new feature/payment

チーム共有のベストプラクティス

1. .claude/settings.json を Git 管理

# プロジェクト共通設定をコミット
git add .claude/settings.json
git commit -m "Add Claude Code configuration"

2. .claude/settings.local.json は個人用

{
  "permissions": {
    "additionalDirectories": [
      "./my-experimental-feature",  // 個人的な実験用 worktree
      "~/personal-scripts"           // 個人的なスクリプト
    ]
  }
}

3. README にセットアップ手順を記載

## 開発環境セットアップ

### Claude Code + git worktree

```bash
# 初期セットアップ
./setup-claude-worktree.sh

# Claude Code 起動
claude

# worktree 作成
multi-wt-new feature/your-feature
```

Discussion