Claude Codeの--worktreeオプションとgit worktreeの活用
概要
Claude Codeに--worktree（短縮: -w）というCLIフラグが追加された。これはgit worktreeを使って隔離された作業ディレクトリを自動的に作成し、その中でClaude Codeセッションを開始する機能。並列で複数のタスクを進めたいときに便利。
自分はすでにgit worktreeを日常的に使っており、カスタムコマンドやスキルで独自のワークフローを組んでいたので、--worktreeオプション自体は直接必要ではなかった。ただ、この機会に既存の仕組みを見直して、worktree向けに最適化された専用サブエージェントを新たに定義した。そのまとめ。
Claude Codeの--worktreeオプション
--worktree（-w）フラグを付けてClaude Codeを起動すると、git worktree内で隔離されたセッションが始まる。
使い方は以下の通り。
# 名前を指定して起動
claude --worktree feature-auth
# または短縮形
claude -w feature-auth
# 名前を省略すると自動生成される
claude --worktree
worktreeの作成先は<repo>/.claude/worktrees/<name>/で、ブランチ名はworktree-<name>になる。デフォルトのリモートブランチから分岐する。例えば~/repos/project/で作業していてclaude -w my-featureとすると、~/repos/project/.claude/worktrees/my-feature/にworktreeが作られる。
注目すべきは、プロジェクトルートのworktrees/ではなく、.claude/worktrees/の下に作られるという点。.claude/はClaude Codeの設定ディレクトリ（settings.jsonやエージェント定義などが置かれる場所）なので、その中にworktreeが作られるのは少し意外に感じるかもしれない。プロジェクトの.gitignoreに.claude/worktrees/を追加しておくとよい。
クリーンアップの挙動がよくできていて、変更なしでセッションを終了するとworktreeとブランチが自動削除される。変更ありで終了すると、残すか削除するか聞いてくれる。
セッション中に「work in a worktree」や「start a worktree」と言うだけでもworktreeが作られるとのこと。
公式ドキュメント:
git worktreeとは
git worktreeは、1つのgitリポジトリから複数の作業ディレクトリを作る仕組み。それぞれのworktreeは独立したブランチをチェックアウトできるが、リポジトリの履歴やリモート接続は共有される。
つまり、あるブランチで機能開発しながら、別のブランチでバグ修正、というのが同時にできる。普通のgit操作だとブランチを切り替えるたびにstashしたり、未コミットの変更を気にしたりする必要があるが、worktreeならそういうのが不要になる。
例えば~/repos/project/で作業しているとして、以下のようにworktreeを作る。
# feature-aブランチ用のworktreeを作成
git worktree add worktrees/feature-a -b feature-a
これで~/repos/project/worktrees/feature-a/というディレクトリが作られて、そこではfeature-aブランチがチェックアウトされた状態になる。元の~/repos/project/はそのまま。worktreeの中でgit操作をすると、そのworktreeでチェックアウトされているブランチに対して操作が適用される。つまり、worktreeごとに独立したワーキングツリーがネストしている形になる。
公式ドキュメント:
一般的な使い方
--worktreeの一般的な使い方としては、複数のターミナルでそれぞれ別のworktreeセッションを動かすパターンがある。
# Terminal 1: 認証機能の開発
claude --worktree feature-auth
# Terminal 2: 同時にバグ修正
claude --worktree bugfix-123
それぞれのセッションは別ブランチ・別ディレクトリで動くので、変更が衝突しない。
手動でworktreeを作ってからClaude Codeを起動する方法もある。
git worktree add ../project-feature-a -b feature-a
cd ../project-feature-a && claude
--worktreeオプションはこの手順を自動化してくれるものなので、やっていることは同じ。
各worktreeでプロジェクトの依存関係のインストール（npm install等）が必要になる場合がある。worktreeはファイルシステム上は別ディレクトリなので、node_modulesは共有されない。
git worktreeを使ったことがない人にとっては、--worktreeオプションはよい入口になると思う。worktreeの作成やクリーンアップをClaude Codeが面倒見てくれるので、git worktreeのコマンドを覚えなくても並列作業の便利さを体験できる。
自分にとってのgit worktree
自分はすでにgit worktreeを日常的に使っており、Claude Codeのカスタムコマンドやスキルで独自のワークフローを構築していた。そのため--worktreeオプション自体は直接の恩恵はなかった。ただ、この機会に既存の仕組みを見直し、いくつかの改善を行った。
/start-wt-devカスタムコマンド
GitHub issueをベースにworktreeを作成するカスタムコマンドがある。GitHub issueのURLや番号を渡すと、issueに対応するworktreeを自動作成してくれる。
/start-wt-dev https://github.com/owner/repo/issues/42
/start-wt-dev 123
/start-wt-dev "Add dark mode toggle"
やっていることは以下の通り。
worktrees/issue-<N>-<slug>/にディレクトリを作成- issueの詳細を含むプロンプトファイル（
__inbox/issue-<N>-prompt-<slug>.md）を生成 - 新しいターミナルで
cdしてClaude Codeセッションを開始するだけの状態にする
このコマンドは公開している。
--worktreeオプションとはworktreeの管理方法が異なる（ブランチ名、ディレクトリ配置、issue連携など）ので、このコマンド自体は今回特に変更なし。
/strategy-git-worktreeスキル
複数のトピックを並列開発するためのスキル。Claude Codeのエージェントチーム機能（TeamCreate + Task tool）を使い、マネージャーエージェントが各トピックのworktreeを作成し、子エージェントをspawnして並列に作業させる。
アーキテクチャはこういう形になっている。
<parent-branch>
└── base/<project-name> (ベースブランチ)
├── <project-name>/topicA (トピックブランチ → base へ PR)
├── <project-name>/topicB
└── <project-name>/topicC
worktrees/
├── <topicA>/ (子エージェントが作業)
├── <topicB>/
└── <topicC>/
マネージャーがベースブランチを作り、そこからトピックごとのworktreeを切り出して、各worktreeで子エージェントが独立して作業する。子エージェントが完了したらトピックブランチからベースブランチへPRを出す、という流れ。
このスキルは公開している。
worktree専用サブエージェントの導入
/strategy-git-worktreeスキルでspawnする子エージェントとして、frontend-worktree-childという専用サブエージェントを新たに定義した。
以前は汎用的なエージェントを使っていたが、worktree固有のルールをエージェント定義として組み込むために専用エージェントに変更した。
- 「自分のworktreeから出ない」「PRはbaseブランチに向ける」「完了したらSendMessageでマネージャーに報告」などのルールが構造的に定義される
- マネージャーが子エージェントに渡すプロンプトから定型的なルールを省略できる
- プロンプトの指示に依存するのではなく、エージェント定義としてルールが固定されるので、書き忘れによる事故がなくなる
また、Claude CodeのTask toolにはisolation: "worktree"というパラメータがあり、これを使うとサブエージェントが自動的にworktree内で作業するようにできる。シンプルな用途にはこれで十分だが、自分の/strategy-git-worktreeのようにブランチのトポロジーやPRのターゲットを細かく制御したい場合は、手動でworktreeを管理して専用サブエージェントに作業させる方がうまくいく。将来的にはこのisolation: "worktree"の仕組みがさらに洗練されて、より多くのケースをカバーできるようになると思われる。
まとめ
git worktreeをまだ使ったことがない人は、--worktreeオプションはよい入口になる。worktreeの作成やクリーンアップをClaude Codeが面倒見てくれるので、並列作業の便利さを手軽に体験できる。
自分のように既にworktreeを活用している人にとっては、--worktree自体よりも、エージェントチーム機能（TeamCreate + Task）との組み合わせが重要になってくると考えている。自分がgit worktreeの存在を知ったのはClaude Codeを使い出した以降で、大きな作業をさせるときは、トピック単位でworktreeを切り、管理させるマネージャーセッションと、切られたworktreeで具体的な実装をするセッションを分け、手動で行ったり来たりしていた。エージェントチーム機能はそういうことを内部的にやってくれるものなので、超巨大タスクを与えても、30分とか1時間とかそれを勝手に割り振ってやってくれるということが可能になる。--worktree単体にも意味はあるが、そういう流れの中でより洗練された結果が得られるようになると考えられる。