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 を再利用できることを確認する。