AI/worktree対応の開発環境設計（Docker Compose・固定コンテナの落とし穴）

Git worktree や複数 checkout から同じ Compose 定義を起動する前提では、container_name と固定ホストポートが衝突原因になりやすい。

判断基準:

• 複数 worktree を同時に起動したいなら、container_name は基本的に指定しない。Compose の project name による自動命名に任せると、worktree ごとにコンテナ名・ネットワーク名・ボリューム名を分離できる。
• ホストから DB や API に接続する必要がある場合、固定の 5432:5432 や 8080:8080 は 2 つ目の worktree で失敗する。${DB_PORT:-5432}:5432 のようにホスト側ポートを環境変数化するか、共有 DB を 1 つだけ起動する設計にする。
• 逆に、全 worktree で 1 つの共有 DB を使う設計なら、COMPOSE_PROJECT_NAME を明示して「常に同じ Compose project を操作する」ことをドキュメント化する。中途半端に project name だけ分かれてコンテナ名だけ固定すると、別 worktree から compose up したときに既存コンテナ名と衝突する。

検証方法: 新しい worktree/checkhout を 2 つ作り、両方で docker compose up -d 相当を実行する。2 つ目で container name conflict や port is already allocated が出るなら worktree 対応として不十分。共有 DB 方針の場合は、2 つ目の checkout から同じ Compose project の既存 DB を再利用できることを確認する。

リポジトリ分割（api/front/mcp など）で AI（Claude Code / Codex 等）に git worktree で作業させたいなら、新しい worktree を切った直後に追加設定なしで build/test ループが回る状態を目標にする。

具体策:

• 開発/テストループをホストネイティブにし、Docker は DB だけに限定する（テストが mock 中心で DB 実行がわずかなら、Docker でテストを回す必然性はない）。
• 環境変数を2層に分離する。コミットする非機密デフォルト（ローカル DB 接続、ダミーの JWT/暗号鍵を含めてよい）だけで起動・テストが通る状態にし、実キーはリポジトリ外の機密ファイル（例 ~/.config/app/secrets.env）に置く。リポジトリ外なら全 worktree から自動参照でき、worktree ごとのコピー作業が不要になる。
• config が env ファイルを直読みする形にして、素の go test ./... が常に通る（direnv や固定コンテナに依存させない）。

『AI と相性が悪い』構成の多くは、gitignore された env・固定コンテナ・direnv 依存が原因で、worktree でゼロ設定起動できない点にある。

Makefile などが docker exec -i <固定コンテナ名> ... 方式でテストを実行し、そのコンテナが本体 checkout（例: .:/app）をマウントしている場合、git worktree からそのコマンドを実行しても、テストされるのは worktree ではなく本体 checkout のコードになる。

AI が「テスト通った」と報告しても worktree の変更は一切検証されていない、という事故が起きる。一般原則として、テストの実行 checkout と検証対象 checkout を一致させること。AI の build/test ループはホスト実行（例: go test ./...）にして、実行したディレクトリのコードがそのまま検証される状態にする。固定コンテナ経由の実行は、マウント元がどの checkout かを常に疑う。

docker compose の environment: APP_ENV: $APP_ENV 形式は、compose を起動したシェルの環境変数に依存する。その値を direnv（.envrc）で供給していて .envrc が gitignore されている場合、worktree を切った瞬間に環境変数が全て消え、スタックが起動すらできなくなる。

direnv が効かないシェル（AI のサブプロセスや CI など）からも起動できるよう、environment: の $VAR 列挙をやめて、コミットした env ファイルを指す env_file: [.env.development] 方式にする。コンテナ起動を gitignore されたシェル env に依存させない。