Claude Code × git worktree で並列開発 — サブモジュール構成のリポジトリで成立させる —

■ タイトル
Claude Code × git worktree で並列開発 — サブモジュール構成のリポジトリで成⽴させる —

■ 概要
AIエージェントを活用した開発が進む中、単一の作業ディレクトリにおけるブランチ切り替え（コンテキスト喪失）や、複数セッションによる編集衝突が新たなボトルネックとなっています[cite: 1]。

本スライドでは、`git worktree` と Claude Code の機能を組み合わせることで、「1人 = Nセッション」の並列開発環境を構築する手法を解説します[cite: 1]。
特に、対応が難しい「サブモジュール構成」のリポジトリにおいて、Claude Codeの `SessionStart hook` を活用して環境を自動整備する方法や、Docker Composeを用いた「アプリ分離・DB共有」の設計ノウハウについて実践的なアプローチを紹介しています[cite: 1]。

■ 対象となる方
- AIエージェント（Claude Code等）を用いたコーディング効率を最大化したいエンジニア
- サブモジュール構成でのローカル開発環境構築に課題を感じている方
- `git worktree` の実用的なユースケースを探している方

■ 主なトピック
- ボトルネックは「人」から「チェックアウト」へ[cite: 1]
- Claude Codeにおける `git worktree` のネイティブサポートと `SessionStart hook`[cite: 1]
- サブモジュール構成の壁と、hookスクリプトを用いた環境の自動整備[cite: 1]
- Docker Compose設計（ポート衝突を防ぐアプリ分離と、DBの共有）[cite: 1]
- 導入時の注意点（マイグレーションの干渉など）と次の一手[cite: 1]

■ 発表情報
2026年8月14日 第152回NearMe技術勉強会[cite: 1]
発表者: Kaito Asahi[cite: 1]

Transcript

1. Claude Code × git worktree で並列開発 — サブモジュール構成のリポジトリで成⽴させる — 2026-08-14 第152回NearMe技術勉強会 Kaito Asahi
2. ボトルネックは「⼈」から「チェックアウト」へ ブランチ切替 = コンテキスト喪失 stash → checkout → 再ビルド。割り込みのたびに作業状態と思考 が途切れる。 セッションは並列、作業場所は 1 つ エージェントは N 並列。 作業ディレクトリは 1。 複数の Claude セッションが同⼀ディレクトリを編集し合い、変更 が衝突する。 待ち時間を活かせない レビュー‧CI を待つ間、次のタスクに安全に着⼿できない。 02 / 13 編集衝突‧順番待ちで、並列化の効果 が相殺される
3. git worktree：作業ディレクトリを複数持てる .git を共有したまま複数チェックアウト .git（共有オブジェクト） 履歴‧オブジェクトは 1 つ。作業ディレクトリだけを複数展開 する。 clone より軽い オブジェクトと fetch を共有。同じブランチを 2 箇所で開くこ とは防いでくれる。 main fix-a feat-b $ git worktree add ../fix-a 独⽴した作業ディレクトリ（ブランチは排他） 過去の勉強会スライドも参考：https://speakerdeck.com/nearme_tech/parallel-ai-coding?slide=4 03 / 13
4. Claude Code は worktree をネイティブサポート claude --worktree <name> セッション専⽤の worktree を⾃動作成。終了時、未変更な ら⾃動削除。 SessionStart hook セッション起動直後に任意の初期化スクリプトを実⾏でき る。ここが今⽇の主役。 04 / 13 .worktreeinclude gitignore 済みの .env などを、新しい worktree に⾃動コ ピーする設定ファイル。 parallel sessions worktree ごとに完全分離。編集衝突なしで N セッションを 同時進⾏できる。
5. サブモジュール構成の壁：サブモジュールが空のまま worktree 直後、サブモジュールは空 $ claude --worktree fix-a git worktree はサブモジュールを init しない。 $ ls services/dispatch/ (empty) 中⾝がほぼサブモジュール 親リポジトリ単体では、ビルドもテストも何も動かない。 upstream でも未解決 claude-code #43730 / #27156。⾃前の対処が必要。 クラウドセッション（--cloud）も単⼀リポジトリ制約で取得不可（#24400）→ 当⾯はローカル⼀択 05 / 13
6. 解決：SessionStart hook で「使える worktree」に⾃動整備 claude --worktree .worktreeinclude SessionStart hook docker compose up セッション起動 .env を⾃動コピー worktree-setup.sh 独⽴スタック起動 worktree-setup.sh がやること 1 06 / 13 2 3 4 submodule update --init --recursive ポートオフセット算出 .env へ書き込み 結果を stdout へ 未初期化のときだけ実⾏ worktree 名から決定的に導出 COMPOSE_PROJECT_NAME + 各ポート変数 = Claude のコンテキストに⼊る
7. compose 設計：アプリは分離、DB は共有 "${WEB_PORT:-3000}:3000" 公開ポートを環境変数化。未設定時は従来値 = メイン環境はデグレな し。 main poc-a poc-b app :3000 app :3100 app :3200 外部ネットワーク経由で接続 COMPOSE_PROJECT_NAME で分離 コンテナ‧ネットワーク名が worktree ごとに分かれ、共存でき る。 マイグレーションの⼆重実⾏に注意 共有 DB seed / migrate は共有 DB を壊しうる。運⽤ルール化が必要。 DB / Redis はメインスタックで 1 つだけ起動 08 / 13
8. デモ：2 worktree‧2 スタック‧DB は 1 つ 1 claude --worktree poc-a hook がポート表を出⼒する 2 2 並列セッション 1 共有 DB 0 ポート衝突 docker compose up :3100 でアプリが起動 3 別ターミナルで poc-b :3200 で並⾛ — 衝突しない 4 DB 接続を確認 双⽅から同じ共有 DB へ 09 / 13
9. 既知の制約と、最初に検証すること submodule × worktree の git 互換性 サブモジュールの git dir は共有 .git/modules 配下。複数 worktree の同時チェックアウトで⼲渉しないか、POC の最初に 必ず検証する。 共有 DB の宿命 破壊的マイグレーション‧スキーマ変更は worktree 間で⼲渉する。実施タイミングの運⽤ルールが要る。 クラウドセッションは対象外 サブモジュール未対応のため nearme-center 起点では使えない。単体サービスのタスクに限り将来検討。 10 / 13
10. 次の⼀⼿ 11 / 13 ドメインルーティング化 サービス単体リポジトリ整備 AI パイプラインへ接続 ポート番号の暗記から卒業。 caddy-docker-proxy で feature-x.localhost に。 単体でテストが回る状態になれば、 --cloud（クラウド実⾏）が解禁さ れる。 計画（ローカル）と実装（別セッ ション‧別モデル）の分業フローに 組み込む。
11. まとめ worktree × Claude Code で「1 ⼈ = N セッション」の並列開発が成⽴する サブモジュールを含むようなものは submodule init とポート分離を hook で⾃動化すれば使える アプリは分離‧DB は共有 — メイン環境はデグレゼロで導⼊できる 12 / 13
12. Thank you