Claude Code Worktree完全ガイド｜–worktreeフラグで並列開発・ブランチ競合ゼロを実現する方法

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

# 短縮フラグ（-w）も使える
claude -w bugfix-login

# 名前を省略すると自動生成（例: bright-running-fox）
claude --worktree

my-project/
├── .git/                          ← すべてのworktreeが共有するgit管理
│   └── worktrees/
│       └── feature-auth/          ← git内部のworktree管理ファイル
├── .claude/
│   └── worktrees/
│       └── feature-auth/          ← Claude Codeの作業ディレクトリ（ここで作業）
│           ├── src/               ← リポジトリのファイルが展開される
│           ├── package.json
│           └── ...
├── src/                           ← メインブランチの作業ディレクトリ（変更されない）
├── package.json
└── ...

echo ".claude/worktrees/" >> .gitignore

# Worktreeセッションでコミットあり → 終了時に選択肢が表示される
# Claude Code:
# "The worktree has changes. Would you like to keep or remove it?"
# > keep  → .claude/worktrees/feature-auth/ とブランチ worktree-feature-auth が保存される
# > remove → 両方削除（変更は失われる）

# keepした場合: 後からマージする
git merge worktree-feature-auth

# keepした場合: PRを作成する
gh pr create --head worktree-feature-auth --title "feature: ログイン認証機能の追加"

# ターミナル1: メインブランチで通常作業
claude

# ターミナル2: ログイン機能の実装（新しいWorktreeで）
claude --worktree feature-login

# ターミナル3: ダッシュボードのUIバグ修正（別のWorktreeで）
claude --worktree bugfix-dashboard

# 各ターミナルで独立して作業できる
# → ターミナル2のファイル変更がターミナル1やターミナル3に影響しない

# Worktreeをtmuxセッションとして起動（iTerm2がある場合はネイティブペインを使用）
claude --worktree feature-auth --tmux

# 従来のtmuxを使いたい場合
claude --worktree feature-auth --tmux=classic

# tmuxの基本操作（参考）
# Ctrl+B → c: 新しいウィンドウ（タブ）を作成
# Ctrl+B → n: 次のウィンドウへ移動
# Ctrl+B → 数字: 指定番号のウィンドウへ移動

---
name: experimental-refactor
description: 実験的なリファクタリングを隔離されたWorktreeで実行する
isolation: worktree
---

あなたはリファクタリング専門のエージェントです。

与えられたコードを現代的なパターンに書き直してください。
実験的な変更を行うため、このWorktreeの変更がメインブランチに
影響しないことを前提として自由に変更してください。

変更後は必ず:
1. テストを実行して動作確認する
2. 変更内容のサマリーを作成する
3. 本採用すべき変更と、実験的すぎて採用しない変更を分類する

# ── セットアップ ──────────────────────────────────
# .gitignoreにWorktreeディレクトリを追加（初回のみ）
echo ".claude/worktrees/" >> .gitignore

# ── ターミナル1: 新機能の実装 ─────────────────────
claude --worktree feature-payment

# Worktree内でClaudeに指示
> 決済フローにStripe決済を追加してください。
> src/services/payment.ts を新規作成して、
> src/routes/checkout.ts から呼び出す実装にしてください。

# ── ターミナル2: バグ修正（別ターミナル）──────────
claude --worktree bugfix-cart-total

> カート合計金額の計算がおかしい。
> src/utils/cart.ts の computeTotal() 関数を調べて修正してください。
> テストも更新してください。

# ── 作業完了後: それぞれをPR化 ───────────────────
# ターミナル1で
git push origin worktree-feature-payment
gh pr create --head worktree-feature-payment

# ターミナル2で
git push origin worktree-bugfix-cart-total
gh pr create --head worktree-bugfix-cart-total

# ── ターミナル1: メインセッションで計画（Plan Mode）──
claude

/plan
> src/ 全体を読んで、認証システムをJWTからセッションベースに移行する計画を作ってください。
> 影響するファイルと変更順序を詳しく教えてください。（変更はしないでください）

# 計画を確認・承認

# ── ターミナル2: Worktreeで実装開始 ──────────────────
claude --worktree auth-migration

> 今から認証システムをJWTからセッションベースに移行します。
> まずsrc/middleware/auth.ts を修正してください。

# 既存ブランチをWorktreeに追加
git worktree add .claude/worktrees/existing-feature existing-feature-branch

# Worktreeのディレクトリでclaude起動
cd .claude/worktrees/existing-feature
claude

# 作業完了後: Worktreeを削除
cd ../../..
git worktree remove .claude/worktrees/existing-feature

# 全Worktreeの一覧を確認
git worktree list