20
9

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kazuki_ogawa(kazuki ogawa)in株式会社シンシア

git-worktree-runner (gtr) で実現するAI時代の並列開発

Posted at

株式会社シンシアでは、実務未経験のエンジニアの方や学生エンジニアインターンを採用し一緒に働いています。
※ シンシアにおける働き方の様子はこちら

シンシアでは、年間100人程度の実務未経験の方が応募し技術面接を受けます。その経験を通し、実務未経験者の方にぜひ身につけて欲しい技術力（文法）をここでは紹介していきます。

はじめに

Claude Code、Cursor、Aider、Cline、Devin...

2024年から2025年にかけて、AIコーディングエージェントが急速に普及しました。これらのツールを使い始めて、「開発速度が爆速になった」と感じている人は多いはず。

でも、こんな経験はありませんか？

  • AIエージェントに作業を任せている間、自分は待っているだけになる
  • 「feature-Aの作業中にhotfixの依頼が来て」集中が途切れる
  • stash → checkout → 作業 → checkout → stash pop のブランチ切り替えが面倒

AI時代の開発ボトルネックは「コードを書く時間」から**「待ち時間」と「切り替えコスト」**に移行しています。

この記事では、git worktreeの基本と、それをさらに使いやすくするgit-worktree-runner (gtr) というツールを紹介します。

対象読者

  • Claude Code、Cursor、AiderなどAIコーディングエージェントを使っている開発者
  • 複数タスクのブランチ切り替えにストレスを感じている人
  • 1人で複数案件を効率的に回したい人

Part 1: git worktreeを理解する

git worktreeとは

1つのリポジトリで、複数のブランチを別々のディレクトリで同時に開ける機能です。

Git 2.5（2015年7月リリース）で追加された、実は10年近く前からある機能。しかし、知名度が低く「知る人ぞ知る」状態でした。

なぜ今まで流行らなかったのか

  • 素のコマンドが冗長で使いにくい
  • 1人で複数ブランチを同時に作業するニーズが少なかった
  • IDEのGit統合が進み、ブランチ切り替えで十分だった
# 素のgit worktreeコマンド（長い...）
git worktree add ../my-app-worktrees/feature-a feature-a
git worktree add ../my-app-worktrees/hotfix-123 hotfix-123
git worktree list
git worktree remove ../my-app-worktrees/feature-a

なぜ今、注目されているのか

AIコーディングエージェントの登場で状況が変わりました。

従来の開発 AI時代の開発
1人1タスクが基本 AIに任せて並列化が可能
コードを書く時間がボトルネック 待ち時間・切り替えコストがボトルネック
ブランチ切り替えで十分 物理的に分離したい

AIエージェントは「自律的に作業を進めてくれる」ので、人間が複数のAIを同時に走らせることが現実的になりました。そのためには、ブランチごとに独立したディレクトリが必要。そこでgit worktreeが再評価されています。

従来のやり方との比較

状況 従来のやり方 git worktreeを使う場合
feature-A作業中にhotfix依頼 stash → checkout → 作業 → checkout → stash pop 別ディレクトリで即作業開始
2つの案件を並行作業 頻繁にブランチ切り替え 2つのディレクトリを開いておく
AIに任せながら他の作業 終わるまで待つ 別ディレクトリで自分は別作業

ディレクトリ構成イメージ

~/projects/
├── my-app/                    # メインのリポジトリ (mainブランチ)
└── my-app-worktrees/          # worktree用ディレクトリ
    ├── feature-a/             # feature-aブランチ ← 自分が作業中
    └── feature-b/             # feature-bブランチ ← AIエージェントが作業中

ポイント: 全部同じリポジトリを共有しているので、.gitは1つだけ。コミット履歴も共有されます。

素のgit worktreeコマンド

# worktree作成（既存ブランチ）
git worktree add ../my-app-worktrees/feature-a feature-a

# worktree作成（新規ブランチ）
git worktree add -b feature-b ../my-app-worktrees/feature-b

# 一覧表示
git worktree list

# worktree削除
git worktree remove ../my-app-worktrees/feature-a

# 不要なworktree情報をクリーンアップ
git worktree prune

Part 2: git-worktree-runner (gtr) で効率化

gtrとは

素のgit worktreeコマンドは冗長で使いにくい。

git-worktree-runner (gtr) は、CodeRabbit社が開発したgit worktreeのラッパーCLIツールです。worktreeの操作をシンプルにし、エディタやAIツールとの連携機能を提供します。

GitHub: https://github.com/coderabbitai/git-worktree-runner

gtrの主な機能

機能 説明
シンプルなコマンド git gtr new feature-a で作成完了
エディタ連携 git gtr editor feature-a でCursor/VS Codeで開く
AIツール連携 git gtr ai feature-a でClaude Code/Aider等を起動
設定ファイル自動コピー .envなどを新しいworktreeに自動コピー
フック機能 worktree作成後にnpm installを自動実行など

素のコマンドとの比較

操作 git worktree gtr
作成 git worktree add ../repo-wt/feat feat git gtr new feat
エディタで開く cd ../repo-wt/feat && cursor . git gtr editor feat
AIツール起動 cd ../repo-wt/feat && claude git gtr ai feat
一覧 git worktree list git gtr list
削除 git worktree remove ../repo-wt/feat git gtr rm feat

インストール方法

# リポジトリをクローン
git clone https://github.com/coderabbitai/git-worktree-runner.git
cd git-worktree-runner

# PATHに追加（シンボリックリンク）
sudo ln -s "$(pwd)/bin/git-gtr" /usr/local/bin/git-gtr

初期設定

# デフォルトエディタを設定（Cursorの場合）
git gtr config set gtr.editor.default cursor

# デフォルトAIツールを設定（Claude Codeの場合）
git gtr config set gtr.ai.default claude

# worktree作成後に自動実行するコマンド（任意）
git gtr config add gtr.hook.postCreate "npm install"

対応しているAIツール

ツール 設定値
Claude Code claude
Aider aider
Cursor (Agent) cursor
Codex CLI codex
Gemini CLI gemini
Continue continue
OpenCode opencode

Part 3: 実践ワークフロー

基本的な使い方

# 1. worktree作成
git gtr new feature-a

# 2. エディタで開く
git gtr editor feature-a

# 3. AIツールを起動
git gtr ai feature-a

# 4. 一覧表示
git gtr list

# 5. 作業完了後、削除
git gtr rm feature-a

並列作業のワークフロー例

# ターミナル1: feature-aを自分で作業
git gtr new feature-a
git gtr editor feature-a
# → Cursorで手動コーディング

# ターミナル2: feature-bをAIエージェントに任せる
git gtr new feature-b
git gtr ai feature-b
# → AIエージェントが自動でコーディング

# 両方同時に進行！

実際の活用シーン

シーン1: AIに任せながら自分も作業

自分: feature-a（UIコンポーネント作成）をCursorで手動実装
AIエージェント: feature-b（API実装）を自動生成

→ 待ち時間ゼロで両方進む

シーン2: 急なhotfix対応

feature-a作業中にhotfix依頼が来た

従来: stash → checkout → 修正 → checkout → stash pop（面倒）
gtr: git gtr new hotfix → 修正 → git gtr rm hotfix（スムーズ）

シーン3: PRレビューしながら開発

自分: feature-aの開発を継続
別worktree: 同僚のPRブランチをチェックアウトしてレビュー

→ コンテキストスイッチなしで両立

良かった点・注意点

良かった点 注意点
AIの待ち時間を有効活用できる ディスク容量を使う（worktreeごとにファイルが増える）
ブランチ切り替えのストレスがない 同じブランチを複数worktreeで開かない方が良い
複数案件の並行管理がしやすい node_modules等は各worktreeでnpm install必要
各種AIエージェントとの相性が良い 最初の設定が少し必要

現実的な並列数の限界

「並列化できる」と言っても、無限にタスクを増やせるわけではないです。

私の場合、最大3タスクが限界でした。理由は2つ：

  1. コンフリクトの問題 - 同時に触るファイルが増えると、マージ時にコンフリクトが頻発する。3タスク程度なら、担当範囲を分けやすい
  2. 頭の中の管理限界 - 「今どのworktreeで何をやっているか」を把握できるのは、自分の場合3つが限界だった

最初は2タスク並列から始めて、自分の限界を探ってみるのがおすすめです。

Docker環境での注意点

gtrはとても便利なツールですが、Docker環境で開発している場合は追加の考慮が必要です。私自身がハマったポイントを共有します。

問題1: worktreeがコンテナから見えない

gtrでworktreeを作成すると、デフォルトではリポジトリの親ディレクトリに作成されます。

~/projects/
├── my-app/                    # メインリポジトリ（コンテナにマウント済み）
└── my-app-worktrees/          # ← ここはマウントされていない！
    └── feature-a/

docker-compose.ymlで./:/appのようにメインリポジトリだけをマウントしていると、worktreeディレクトリはコンテナ内からアクセスできません。

問題2: ホストとコンテナのパス不一致

ホスト側とコンテナ内でパスが異なるケースが多いです。

gtrはホスト側で動くため、git gtr go feature-aで返されるパスはホストのパス。コンテナ内では使えません。

解決策: worktreeごとにDockerコンテナを分ける

各worktreeで独立したDockerコンテナを起動する構成がおすすめです。

ポイント:

  • メインリポジトリのDBコンテナを共有
  • 各worktreeのアプリは別ポートで起動
  • コンテナ名も分けて衝突を回避

フックで自動セットアップ

gtrのpostCreateフックを使うと、worktree作成時に環境設定を自動化できます。

フック内では以下の環境変数が利用可能:

環境変数 内容
REPO_ROOT リポジトリルートのパス
WORKTREE_PATH 作成されたworktreeのパス
BRANCH ブランチ名

セットアップスクリプトの例

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

# 既存のworktree数をカウントしてインデックスを決定
WORKTREE_COUNT=$(git worktree list | wc -l)
WORKTREE_INDEX=$((WORKTREE_COUNT - 1))
APP_PORT=$((3000 + WORKTREE_INDEX))

# .envファイルを生成
cp .env.example .env
echo "WORKTREE_INDEX=${WORKTREE_INDEX}" >> .env
echo "APP_PORT=${APP_PORT}" >> .env

# docker-compose.override.ymlをコピー
cp docker-compose.override.yml.example docker-compose.override.yml

echo "Setup complete: WORKTREE_INDEX=${WORKTREE_INDEX}, APP_PORT=${APP_PORT}"

.gtrconfigでフックを設定

[copy]
include = .env.example
include = docker-compose.override.yml.example
include = scripts/setup-worktree.sh

[hooks]
postCreate = bash scripts/setup-worktree.sh

[defaults]
editor = vscode
ai = claude

docker-compose.override.yml.example

# Worktree用Docker設定
services:
  app:
    container_name: app_wt${WORKTREE_INDEX:-0}
    ports: !override
      - "${APP_PORT:-3000}:3000"
    environment:
      DB_HOST: host.docker.internal  # メインのDBを参照

  db:
    deploy:
      replicas: 0  # DBは起動しない（メインを共有）

Docker + gtrの実践ワークフロー

# 1. worktree作成（フックで.envとdocker-compose.override.ymlが自動生成）
git gtr new feature-coupon

# 2. worktreeに移動
cd "$(git gtr go feature-coupon)"

# 3. Dockerコンテナを起動
docker compose up -d

# 4. Claude Codeで開発
git gtr ai feature-coupon

フックのおかげで、手動での環境設定が不要になります。

まとめ

  • git worktreeはGit 2.5（2015年）からある機能だが、AIエージェント時代に再評価
  • AI時代のボトルネックは「書く時間」から「待ち時間・切り替えコスト」へ
  • git-worktree-runner (gtr) でworktree管理がシンプルに
  • 「AIに任せて待つ」から**「AIと並列で動く」**へ開発スタイルを転換

まずは2つのworktreeを作って、並列作業の効果を体感してみてください！

参考

20
9
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
20
9

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?