git worktreeとDocker Volumeスナップショットで実現するAIエージェント並行開発環境

2025年12月17日AI,DB,Git,データベース,働き方,自動化

お疲れ様です！IT業界で働くアライグマです！

AIコーディングエージェントの登場で、複数の機能を並行して開発する機会が増えました。Cursorやmistral-vibeなどのエージェントに任せている間に別の作業を進めたり、レビュー待ちのブランチを放置して次のタスクに取りかかったり。こうした並行開発では、コンテキストスイッチのコストが大きな課題になります。

「git stashで退避したけど、どれがどれだか分からなくなった」「ブランチを切り替えたらDBのマイグレーション状態がずれて動かなくなった」——そんな経験はありませんか？

本記事では、git worktreeとDocker Volumeスナップショットを組み合わせて、ブランチごとにデータベースも含めた開発環境を分離する方法を解説します。

Contents

1. 並行開発の課題とgit worktreeの基本
2. 前提条件と環境構成
- 2.1. compose.yamlの環境変数対応
3. git worktreeとDocker Volumeの連携設定
- 3.1. git worktreeの作成
- 3.2. Docker Volumeのスナップショット作成
4. ケーススタディ：AIエージェント並行開発での活用
5. まとめ
- 5.1. 厳しめIT女子アラ美による解説ショート動画はこちら

並行開発の課題とgit worktreeの基本

従来のGit運用では、ブランチを切り替えるたびに作業ディレクトリの状態が変わります。これ自体は問題ありませんが、データベースやキャッシュなどの永続化ミドルウェアは切り替わりません。

たとえば、feature-Aブランチでマイグレーションを実行した後、feature-Bブランチに切り替えると、DBのスキーマはfeature-Aの状態のままです。feature-Bで別のマイグレーションを実行すると、両方のマイグレーションが混在した状態になり、どちらのブランチに戻っても整合性が取れなくなります。

git worktreeは、1つのリポジトリから複数の作業ディレクトリを作成できる機能です。達人プログラマーで紹介されている「DRY原則」の考え方を応用すると、リポジトリのクローンを複数作るのではなく、worktreeで作業ディレクトリだけを分離する方が効率的です。

git worktreeの基本的な使い方については、CursorでローカルLLMを使う完全ガイドでも触れていますが、本記事ではDocker Volumeとの組み合わせに焦点を当てます。

前提条件と環境構成

本記事で紹介する手法を実践するには、以下の環境が必要です。

Git 2.20以上（worktree機能が安定しているバージョン）
Docker 20.10以上（Volume操作が安定しているバージョン）
Docker Compose v2（compose.yamlでの環境変数展開をサポート）
シェル環境（bash/zsh）

想定する読者は、Gitの基本操作（clone, branch, checkout）とDockerの基本操作（build, up, down）を理解しているエンジニアです。Kubernetes完全ガイド第2版で紹介されているDocker Volumeの基礎知識があると、より理解が深まります。

本記事のサンプルでは、PostgreSQLをデータベースとして使用しますが、MySQLやMongoDBなど他のミドルウェアでも同様の手法が適用できます。私のチームではRedisのキャッシュデータも同様にVolume分離していますが、DBほど頻繁にスナップショットを取る必要はありませんでした。

compose.yamlの環境変数対応

Docker Compose v2では、環境変数を使ってVolume名を動的に指定できます。以下のようにcompose.yamlを設定しておくと、worktreeごとに異なるVolumeを使用できます。

services:
  db:
    image: postgres:15
    volumes:
      - ${POSTGRES_VOLUME:-project_postgres_data}:/var/lib/postgresql/data
    environment:
      POSTGRES_PASSWORD: password

この設定により、環境変数POSTGRES_VOLUMEが設定されていればその値を、設定されていなければデフォルト値（project_postgres_data）を使用します。PjMとしてチームに展開する際、この「デフォルト値付き環境変数」の仕組みが非常に役立ちました。既存の開発者は何も変更せずに従来どおり動作し、worktreeを使いたい開発者だけが環境変数を設定すればよいからです。

AIエージェントを活用した開発フローについては、AIコーディングエージェント時代にエンジニアが生き残るための働き方シフト戦略も参考にしてください。

git worktreeとDocker Volumeの連携設定

ここからは、具体的な設定手順を説明します。

git worktreeの作成

まず、メインの作業ディレクトリとは別に、worktreeを作成します。

# 現在のブランチを確認
git branch

# feature-aブランチ用のworktreeを作成
git worktree add ../project-feature-a feature-a

# feature-bブランチ用のworktreeを作成
git worktree add ../project-feature-b feature-b

# worktree一覧を確認
git worktree list

これで、../project-feature-aと../project-feature-bにそれぞれのブランチの作業ディレクトリが作成されます。私が初めてこの手法を試したときは、「こんな簡単にブランチごとに作業ディレクトリを分けられるのか」と驚きました。PjMとして複数の機能開発を並行で管理する立場では、この「ブランチ切り替えなしで並行作業」が非常に便利です。

Docker Volumeのスナップショット作成

次に、現在のデータベースの状態をスナップショットとして保存します。

# 現在のVolumeを確認
docker volume ls | grep postgres

# スナップショット用のVolumeを作成
docker run --rm \
  -v project_postgres_data:/source:ro \
  -v project_postgres_snapshot:/dest \
  alpine sh -c "cd /source && cp -a . /dest"

# feature-a用のVolumeを作成
docker run --rm \
  -v project_postgres_snapshot:/source:ro \
  -v project_feature_a_postgres:/dest \
  alpine sh -c "cd /source && cp -a . /dest"

# feature-b用のVolumeを作成
docker run --rm \
  -v project_postgres_snapshot:/source:ro \
  -v project_feature_b_postgres:/dest \
  alpine sh -c "cd /source && cp -a . /dest"

インフラエンジニアの教科書で解説されているように、Volumeのコピーはコンテナを経由して行う必要があります。直接ファイルシステムを操作するよりも安全で移植性が高い方法です。

Dockerの基本的な使い方については、macOSネイティブLinuxコンテナ入門も参考にしてください。

ケーススタディ：AIエージェント並行開発での活用

私のチームでは、この手法を導入してから並行開発の効率が大幅に改善しました。具体的な事例を紹介します。

状況（Before）

4人のエンジニアが1つのリポジトリで開発しており、それぞれがCursorを使ってAIエージェントに機能実装を任せていました。しかし、以下の問題が頻発していました。

ブランチ切り替え時にDBマイグレーションの競合が発生（週に3〜4回）
git stashの取り違えによる作業ロス（1回あたり30分〜1時間）
「動かなくなった」報告のうち、環境起因が約40%

行動（Action）

上記の手法を導入し、さらに以下のスクリプトを作成して自動化しました。

#!/bin/bash
# wtp (worktree-postgres) - worktree作成時にDB Volumeも自動作成

BRANCH_NAME=$1
WORKTREE_PATH="../project-${BRANCH_NAME}"

# worktree作成
git worktree add "$WORKTREE_PATH" "$BRANCH_NAME"

# Volume名を生成（ブランチ名からスラッシュを除去）
VOLUME_NAME="project_${BRANCH_NAME//\//_}_postgres"

# スナップショットからVolumeを作成
docker run --rm \
  -v project_postgres_snapshot:/source:ro \
  -v "$VOLUME_NAME":/dest \
  alpine sh -c "cd /source && cp -a . /dest"

# compose.yamlの環境変数を設定
echo "POSTGRES_VOLUME=$VOLUME_NAME" > "$WORKTREE_PATH/.env.local"

echo "Created worktree at $WORKTREE_PATH with volume $VOLUME_NAME"

リファクタリング(第2版)で紹介されている「小さなステップで改善する」アプローチに従い、まず1人のエンジニアで試験導入し、問題がないことを確認してからチーム全体に展開しました。