見出し画像

git worktreeでClaude Codeが変わった 並行作業と.env管理の話

たきびラボ | AIで副業

Claude Code がバージョン 2.1.50 になって、「git worktree」関連の機能がいくつか入りました。

「worktreeって何？」という方もいると思うので、Gitの基礎からていねいに説明します。途中で「あ、これ知りたかったやつだ」と思ってもらえたら嬉しいです。あと最後に、.env ファイルにまつわる落とし穴も書いてあるので、現役で使っている方もぜひ最後まで読んでみてください。

この記事でわかること

  • Claude Code 2.1.50 の git worktree 関連の変更点

  • git worktree とは何か（Gitが初めての人にも）

  • なぜ worktree が便利なのか

  • 使うときの注意点（.env の扱いが特に重要）


1. Claude Code 2.1.50 で何が変わった？

今回のアップデートで入った worktree 関連の変更を3つに絞って紹介します。

WorktreeCreate / WorktreeRemove フック

「フック」とは、特定の操作が起きたタイミングで自動実行されるスクリプトのことです。

今回から、worktree を作成・削除するときの Git の動作を完全に独自のスクリプトで置き換えられるようになりました。

一番の活用場面は、Git 以外のバージョン管理システム（SVN・Perforce・Mercurial など）を使っている環境です。たとえば SVN を使うプロジェクトで Claude Code の worktree 機能を使いたい場合、このフックに「SVN で作業コピーを作る処理」を書けば、Claude Code が内部で自動的に呼び出してくれます。

WorktreeCreate フックは、作成したディレクトリのパスを stdout に出力する必要があります。Claude Code はそのパスを作業ディレクトリとして使います。WorktreeRemove フックは削除後の後処理（ログ記録や一時ファイルの掃除など）に使います。

`isolation: worktree`（エージェント定義での自動分離）

Claude Code には「サブエージェント（別の AI エージェントに作業を任せる機能）」があります。今回から、そのエージェントを定義するときに `isolation: "worktree"` と書けるようになりました。

これを指定すると、エージェントが作業するとき自動的に 専用の worktree（作業コピー）が割り当てられます。エージェントの作業が本流のコードに干渉しないので、「エージェントに任せたら大事なファイルが書き換わっていた」という事故を防げます。


シンボリックリンク環境でのセッション表示バグ修正

少しマニアックな話ですが、プロジェクトのディレクトリをシンボリックリンク（別の場所を指す「ショートカット」のようなもの）として作っている環境では、前回のセッションを再開しようとしても画面上に表示されないというバグがありました。

これは worktree に限らず、symlink を含む作業ディレクトリ全般で起きていた問題です。起動タイミングによってセッションの保存先パスの解決が変わってしまうことが原因で、今回修正されています。

2. そもそも git worktree って何？（Git入門者向け）

「worktree の話をする前に、Git 自体がよくわからない」という方のために、少し遠回りして説明します。

Git は「変更の履歴を管理する」ツール

Git とは、プログラムのコードや文書などのファイルに対して、「誰が・いつ・何を変えたか」を記録し続けるツールです。バックアップ機能と、チームでの共同編集機能が合体したようなものです。

「ブランチ」は、その Git の中でも特に重要な概念で、「作業の並行ライン」のことです。たとえば「本番用」のコードを触らずに、「新機能開発用」のコードを別の場所で試せる仕組みです。

普通のブランチ切り替え vs. worktree の違い

通常の Git 操作では、ブランチを切り替えるとファイルの内容そのものが変わります。

feature ブランチ → hotfix ブランチに切り替える
→ フォルダの中身が丸ごと入れ替わる
→ 作業中だったファイルは一時保存（stash）が必要

これが地味にストレスで、「stash してブランチ切り替えて、作業して、戻って、stash pop して...」という手順を何度も繰り返すことになります。

git worktree を使うと、同じリポジトリを複数のフォルダに同時展開できます。

100_Git/
├── image-generate/          ← main ブランチの作業フォルダ
└── image-generate-feature/  ← feature ブランチの作業フォルダ

フォルダを行き来するだけで、stash もブランチ切り替えも不要です。2つのウィンドウを並べて、同時に別々の作業ができます。

3. なぜ worktree が有効なのか

Claude Code の並列エージェントとの相性が抜群

Claude Code では、複数の AI エージェントに並行して作業を任せることができます。このとき、全エージェントが同じフォルダで動くと、ファイルの競合（上書き事故）が起きる可能性があります。

worktree を使うと、エージェントごとに独立した作業環境を用意できます。エージェント A が feature ブランチで新機能を開発しているあいだ、エージェント B は hotfix ブランチでバグ修正をする、といった使い方が安全にできます。

stash の煩わしさがなくなる

「stash（スタッシュ）」は、作業中の変更を一時保存しておく機能です。便利なのですが、「どの stash が何だったか」が後からわかりにくくなる問題があります。worktree があれば stash は原則不要で、この問題を根本から解決できます。

実際の使用例

私が使っている場面で言うと、「記事を書きながら、別ブランチで画像生成スクリプトの改修をする」というのが典型的なパターンです。どちらも中断したくないし、互いに干渉してほしくない。そういうとき、worktree は静かに仕事をしてくれます。

4. 注意点──.env の取り扱いが一番の落とし穴

worktree を使い始めるとき、一番やらかしやすいのが .env ファイルの管理です。

.env はworktree間で共有されない

`.env` ファイルは、API キーやデータベースのパスワードなどを書いておくファイルです。セキュリティ上、Git の管理対象外（.gitignore）にしておくのが基本です。

worktree を作ると、新しいフォルダには .env がコピーされません。 元のフォルダには存在するけど、worktree 側にはない、という状態になります。


これに気づかずスクリプトを実行すると「環境変数が見つかりません」というエラーになります。はじめてやると「なんで動かないんだ？」と数分悩むはめになります（なりました）。

.envをgit追跡してしまうリスク

焦って解決しようとしたとき、うっかり `.env` を `git add` してしまうと大変なことになります。

Git に追跡されてしまった .env は、git の履歴に永遠に残ります。 ファイルを削除しても、過去のコミットを辿れば内容が丸見えです。GitHub にプッシュした瞬間に API キーが漏洩します。

正しい管理法

まず大前提として、`.env` は Git の管理対象から外しておきます。

① .gitignore に必ず記載する

.env
.env.local

これが最初の防衛線です。`.gitignore` に書かれているファイルは Git が追跡しません。

② シンボリックリンクで1箇所管理する（並列作業時の実用解）

「worktreeを作るたびに `.env` をコピーして値を書き込む」は面倒です。Claude Code で複数の worktree を並列で動かしていると、この手間が何度も発生します。

実用的な解決策は シンボリックリンク です。メインリポジトリの `.env` を指すリンクを各 worktree に1回張るだけで、値の管理は1箇所で済みます。

# worktree 作成後、そのディレクトリで1回だけ実行
ln -sf /path/to/main-repo/.env .env

これでメインの `.env` を変更すれば全 worktree に即時反映されます。シンボリックリンク自体は `.gitignore` の対象外ですが、リンク先の `.env` が追跡されていなければ問題ありません。

③ WorktreeCreate フックで完全自動化する（上級者向け）

毎回コマンドを叩くのも面倒という場合は、`.claude/settings.local.json` にフックを設定することで自動化できます。

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; git worktree add -b \"$NAME\" \"$DIR\" >/dev/null 2>&1; ln -sf \"$CLAUDE_PROJECT_DIR/.env\" \"$DIR/.env\"; echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

worktree が作られるたびに自動でシンボリックリンクが張られます。一度設定すれば以後は何も意識しなくて済みます。なお `WorktreeCreate` フックは git の動作を丸ごと置き換えるため、`git worktree add` もスクリプト内で明示的に呼ぶ必要があります。

ℹ️動作確認済み(もし不具合あればコメントいただけると助かります! ) 

正しくSymbolicLinkされていることが分かりました。

④ .env.example で雛形も残しておく

チームで使う場合や、後から見返したとき用に「どんなキーが必要か」を示す雛形ファイルも Git で管理しておくと親切です。

# .env.example（これは Git で管理してOK）
OPENAI_API_KEY=your_api_key_here
DATABASE_URL=your_database_url_here

git履歴に混入した場合の危険性

「もし .env を間違えてコミットしてしまったら？」という話もしておきます。

履歴から完全に消すには `git filter-branch` や `git filter-repo` を使う必要があり、作業が複雑になります。リモートにプッシュ済みの場合はAPI キーを即座に無効化・再発行するのが最優先です。GitHub は自動でシークレットを検知して警告を出す機能もありますが、過信は禁物です。

5. Claude Codeでの実際の使い方

worktree を使う方法は2つあります。「自分でworktreeセッションを開始する方法」と「サブエージェントに自動的にworktreeを使わせる方法」です。

① `claude --worktree` でセッションを開始する

ターミナルから Claude Code を起動するとき、`--worktree` フラグを付けると、その名前でworktreeが作成され、そのなかでセッションが開始されます。

claude --worktree feature-auth

これを実行すると：

  • `feature-auth` という名前の worktree が `.claude/worktrees/feature-auth` に作成される

  • セッションはそのディレクトリを作業場所として動く

  • メインブランチには干渉しない

既存の Claude Code セッション内でも、Claude に「worktreeを作って作業して」と伝えれば同様に動作します。

② サブエージェントに `isolation: "worktree"` を設定する

「サブエージェント」とは、Claude Code が特定のタスクを別の AI インスタンスに任せる機能です。`.claude/agents/` フォルダに設定ファイルを置くことで、サブエージェントを定義できます。

そのファイルに `isolation: "worktree"` と書くだけで、そのサブエージェントが動くときは必ず専用の worktree が割り当てられます。

---
name: feature-developer
description: 新機能の実装を担当するエージェント
isolation: worktree
tools: Read, Write, Edit, Bash
---

新機能を実装するエージェントです。
メインブランチとは切り離された環境で安全に作業します。

この設定をしておくと、Claude が `feature-developer` エージェントに作業を委任するたびに自動でworktreeが作られます。作業が終わったら 変更がなければ worktree は自動削除、変更があれば「残しますか？」と確認が入ります。

どちらを使えばいいか

  • 自分でコードを書いて試したい → `claude --worktree <name>` で手動セッション

  • Claude に複数の作業を並行させたい → `isolation: "worktree"` をサブエージェントに設定

非エンジニアの方は、まず `claude --worktree <name>` を使ってみるのがわかりやすいと思います。「実験用のコピーを作って、そこで作業する」というイメージです。

6. まとめ

  • Claude Code 2.1.50 では worktree 関連の機能が強化された（フック・エージェント分離・バグ修正）

  • git worktree はブランチを複数フォルダに同時展開する機能。stash 不要で並行作業ができる

  • Claude Code の並列エージェントと組み合わせることで、作業の干渉事故を防げる

  • .env は worktree に引き継がれない。`.gitignore` + `.env.example` の運用が必須

  • .env を間違えて Git に追跡させるとAPI キー漏洩リスクがある

worktree は「知ってから使う」と本当に便利な機能です。一方で、.env の問題は知らないままだと思わぬ事故になりかねない。この記事がその両方を届けられていたら嬉しいです。

この記事が少しでもお役に立てたら、ぜひ「スキ」とアカウントの「フォロー」をお願いします！
普段から AI 開発ツールや Git の実践的な知見を発信していますので、これからも情報を追っていただけるとモチベーションになります。

人気記事:
Claude:

Antigravity:



いいなと思ったら応援しよう！

たきびラボ | AIで副業 よろしければ応援お願いします! 今月のClaude に大切に使わせていただきます!