ワークツリー並行開発

複数の git worktree を同時に動かしてもポートや Docker の Postgres が衝突しない仕組みを用意しています。ワークツリー名から決定論的に レーン番号 (0〜49) を算出し、全ポートをその分だけずらします。

仕組み

ワークツリー名（ブランチ名）をハッシュ → レーン番号を算出。
メインのワークツリーは常に レーン 0（標準ポート）。
.env.local は gitignore 対象。各ワークツリー固有のローカル設定。

生成のトリガー（Claude Code hooks）

.env.local の生成は Claude Code の hooks（.claude/settings.json、コミット済み・全ワークツリー共有）で行う。git フックは claude --worktree で確実に発火しないため使わない。

トリガー	フック	役割
`claude --worktree <name>`	WorktreeCreate (`.claude/hooks/create-worktree.sh`)	worktree を `$HOME/.claude/worktrees/<project>-<branch>` に作成し、`.env.local` を生成。作成パスを stdout に返す（必須契約）。
セッション開始時	SessionStart (`matcher: startup`)	保険。`.env.local` が無ければ `worktree-env.mjs` で生成（冪等）。
`pnpm install`	`prepare` スクリプト	クローン直後の main 用に `.env.local` を生成。

WorktreeCreate は worktree 作成処理そのものを肩代わりするが、ポート/DB の割り当て（.env.local の中身）は scripts/worktree-env.mjs（ハッシュ由来レーン）に委譲してロジックを一元化している。jq が必要。

サービス	ベース	実ポート
Web	3000	3000 + lane
API	3333	3333 + lane
Docs	4321	4321 + lane
Storybook	6006	6006 + lane
Postgres(host)	5432	5432 + lane

Docker は .env.local の COMPOSE_PROJECT_NAME でコンテナ・ボリューム・ネットワークを名前空間分離するため、ワークツリー間で完全に独立します。

使い方

# Claude のワークツリーオプションで作成（WorktreeCreate フックが .env.local を生成）
claude --worktree feat/xxx

# そのワークツリーで
cd ~/.claude/worktrees/commerce-gateway-feat-xxx
pnpm install          # 依存をインストール
pnpm db:setup         # このワークツリー専用の Postgres を起動 + 初期化
pnpm dev              # 衝突しないポートで web/api が起動

手動で git worktree add する場合は、その worktree で一度 pnpm install（または pnpm worktree:env）を実行すれば .env.local が生成される。

コマンド

コマンド	内容
`pnpm worktree:env`	`.env.local` を生成（未存在時のみ）
`pnpm worktree:env:force`	`.env.local` を強制再生成
`pnpm worktree:doctor`	全ワークツリーのレーン/ポートと衝突を点検
`pnpm db:up` / `db:down`	このワークツリーの Postgres 起動/停止
`pnpm db:setup`	DB 起動 + migrate + RLS 適用

レーンが衝突したら

まれにハッシュが衝突して同じレーンになることがあります。pnpm worktree:doctor が検出します。該当ワークツリーで明示的に番号を指定してください。

echo 23 > .worktree-lane     # 0〜49 の空き番号
pnpm worktree:env:force

ルール

ワークツリーごとに .env.local を使う（手で書かず生成に任せる）。
ポートは直書きせず、必ず env 変数（WEB_PORT など）経由で参照する。
ローカル DB は pnpm db:up/db:setup で各ワークツリー専用に立てる。