はじめに
ソーイ株式会社 村上です。
開発していると同時に機能を実装したいと思うことが多いと思います。
- featureブランチで開発中に、本番の緊急バグ対応が入った
-
git stashしてgit checkoutして、対応して、また戻る…を繰り返している - Cursorで作業中にブランチを切り替えたら、AIのコンテキストがぐちゃぐちゃになった
git worktreeを使うことで解決できるということを知っていたのですが、なかなか触れずにいたので今回初めて勉強してステップバイステップの作業をまとめました。
この記事でできるようになること
- 1つのリポジトリで複数ブランチを同時に・独立して作業する
- Cursorのウィンドウを分けることでAIコンテキストを汚さない
- stash不要のクリーンな並列開発フローを身につける
対象読者
- AIエージェントを使っている開発者
- 複数ブランチを同時に触ることが多い方
git worktreeとは？
通常、1つのリポジトリでは1つのブランチしか同時にチェックアウトできません。
myapp/ ← ここでは1ブランチしか作業できない
git worktree を使うと、1つのリポジトリから複数の作業ディレクトリを生やせます。
myapp/ ← main ブランチ（本番対応）
myapp-feature/ ← feature/new-api ブランチ（新機能開発）
myapp-hotfix/ ← hotfix/login-bug ブランチ（緊急対応）
それぞれが独立したディレクトリとして存在するので、ファイルも作業状態も干渉しません。
実案件でのよくあるシーン
よくある具体的なシーンを紹介します。
シーン1：新機能開発中に本番障害の修正が割り込む
Webサービスの新機能をfeatureブランチで実装中、クライアントから「ログインできない」と緊急連絡が入る。
# 従来：開発途中のコードをstashして切り替え
git stash
git checkout main
git checkout -b hotfix/login-bug
# 対応...
git checkout feature/new-dashboard
git stash pop # 作業再開、でもCursorのAIコンテキストはリセット済み
# worktree：切り替え不要、ウィンドウを開くだけ
myapp-feature/ ← 新機能の実装はそのまま残っている
myapp-hotfix/ ← こちらで障害対応
シーン2：レビュー待ちの間に次のタスクを進める
PRを出してレビュー待ちになった間、次のfeatureブランチの作業を始めるケース。レビュー修正が来たときにすぐ切り替えられます。
myapp/ ← main
myapp-pr123/ ← feature/user-profile（レビュー待ち）
myapp-next/ ← feature/notification（次のタスク）
レビューコメントが来たら myapp-pr123/ のウィンドウに切り替えてすぐ修正できます。
ハンズオン
シンプルなリポジトリを作って実際にworktreeを使ってみましょう。
Step 1: サンプルリポジトリの準備
まず練習用のリポジトリを作ります。
mkdir myapp && cd myapp
git init
echo "# MyApp" > README.md
git add . && git commit -m "initial commit"
Step 2: worktreeを追加する
git worktree add コマンドでブランチと作業ディレクトリを同時に作れます。
# feature開発用のworktreeを作成
git worktree add ../myapp-feature -b feature/new-api
# 緊急対応用のworktreeを作成（既存ブランチから）
git worktree add ../myapp-hotfix -b hotfix/login-bug
ディレクトリ構成を確認してみましょう。
ls ../
# myapp/ ← mainブランチ
# myapp-feature/ ← feature/new-apiブランチ
# myapp-hotfix/ ← hotfix/login-bugブランチ
worktreeの一覧も確認できます。
git worktree list
# /path/to/myapp abc1234 [main]
# /path/to/myapp-feature def5678 [feature/new-api]
# /path/to/myapp-hotfix ghi9012 [hotfix/login-bug]
Step 3: Cursorで各worktreeを別ウィンドウで開く
ここがポイントです。
# それぞれのディレクトリをCursorで開く
cursor ../myapp
cursor ../myapp-feature
cursor ../myapp-hotfix
または、Cursorメニューの File → Open Folder で各ディレクトリを開いてください。
workflow別に3つのWindowを開きます。これで3つのブランチを同時に独立した環境で作業できます！
Step 4: 実際に並列作業してみる
それぞれのウィンドウで独立して作業してみましょう。
myapp-feature ウィンドウ（新機能開発）:
cd ../myapp-feature
echo "// new API endpoint" > api.js
git add . && git commit -m "feat: add new API endpoint"
myapp-hotfix ウィンドウ（緊急バグ対応）:
cd ../myapp-hotfix
echo "// fix login bug" > auth.js
git add . && git commit -m "fix: resolve login authentication bug"
どちらの作業も、もう一方のブランチに一切影響しません。
Step 5: Cursor AIを活用する
各ウィンドウで Cmd + K（または Ctrl + K）でCursor AIに質問すると、そのブランチのコードだけを参照して回答してくれます。
例：feature ウィンドウで
「このAPIエンドポイントにバリデーションを追加して」
例：hotfix ウィンドウで
「このauth.jsの修正でセキュリティ上の問題はある?」
ブランチを切り替えていないので、AIが別ブランチのコードを混同することがありません。これがworktreeを使う強いメリットになります。
Step 6: 作業完了後にmainへマージする
worktreeでの作業が終わったら、mainブランチにマージします。worktreeを使っていても、通常のgit操作と変わりません。
mainのディレクトリに移動してマージするだけです。
# mainのディレクトリに移動
cd ../myapp
# hotfixをマージ
git merge hotfix/login-bug
# featureをマージ
git merge feature/new-api
マージ後のクリーンアップ
# worktreeを削除
git worktree remove ../myapp-hotfix
git worktree remove ../myapp-feature
# ブランチも削除
git branch -d hotfix/login-bug
git branch -d feature/new-api
# 残骸のクリーンアップ（念のため）
git worktree prune
よくあるハマりポイントと対処法
node_modulesが重複して容量を食う
worktreeごとに npm install すると、同じ内容の node_modules が増殖します。
対処法：シンボリックリンクで共有する
cd ../myapp-feature
ln -s ../myapp/node_modules ./node_modules
Laravelの場合も同様に vendor ディレクトリをシンボリックリンクできます。
ln -s ../myapp/vendor ./vendor
ただし、ブランチ間でパッケージが異なる場合は使えないので注意。
.envファイルが存在しない
worktreeには .env がコピーされません。
cp ../myapp/.env ../myapp-feature/.env
または .env もシンボリックリンクにする方法もあります（内容が同じ場合のみ）。
同じブランチを2つのworktreeで開こうとするとエラー
# NG: 既にチェックアウト済みのブランチは指定できない
git worktree add ../myapp-main main
# fatal: 'main' is already checked out at '/path/to/myapp'
同じブランチを複数のworktreeで使うことはできません。
まとめ
| 従来のワークフロー | git worktree × Cursor |
|---|---|
| stash → checkout → 作業 → checkout → stash pop | 各ウィンドウでそのまま作業 |
| コンテキストスイッチが多くて疲弊 | ウィンドウを見るだけでコンテキスト切り替え完了 |
| Cursor AIが複数ブランチのコードを混同する可能性 | AIの参照コードが各ウィンドウで完全に独立 |
git worktreeは地味なコマンドですが、Cursorと組み合わせることで開発体験が劇的に向上します。まずはhotfix用のworktreeを使って2つを使うところからはじめていきます。
お知らせ
技術ブログを週1〜2本更新中、ソーイをフォローして最新記事をチェック！
https://qiita.com/organizations/sewii