worktree-parallel

Worktree Parallel Skill - Git Worktree 並列開発支援

目的

同一リポジトリ内で複数の独立タスクを並列に進める際、worktree の配置、ブランチ、ポート、環境ファイル、終了処理を統一する。

SuperPowers の using-git-worktrees で分離ワークスペースを確保したうえで、このスキルのプロジェクト固有ルールを適用する。

---

最重要ルール

• 1 worktree = 1 ブランチ = 1 Issue を原則とする
• worktree はリポジトリルートの .worktrees/ 配下に作成する
• worktree 名はブランチ名の / を - に置換したものにする
• worktree 内のエージェントは自分の worktree 外のファイルを変更しない
• worktree でサーバーを起動する場合は、必ずメインチェックアウト直下のポートレジストリで割り当てられたポートのみを使う
• 作業完了後は git worktree remove と git worktree prune で孤児状態を残さない

---

Step 0: 前提確認

git branch --show-current
git status --short
git worktree list

確認すること:

• 現在のブランチが main / master ではない、またはこれから新規ブランチを作る
• 未コミット変更がある場合、その変更が現在のタスクに関係する
• 既に同じ Issue / ブランチ用の worktree が存在しない

---

Step 1: .worktrees/ の安全確認

.worktrees/ は必ず Git 追跡対象外にする。

bash:

# パスは末尾スラッシュ付きで指定すること（ディレクトリ未作成でも正しく判定するため）
git check-ignore -q .worktrees/ || echo ".worktrees/" >> .gitignore

PowerShell:

git check-ignore -q .worktrees/
if ($LASTEXITCODE -ne 0) { Add-Content -Path .gitignore -Value ".worktrees/" }

.gitignore を変更した場合は、worktree 作成前にその変更をコミット対象として扱う。未追跡の worktree 内容が誤ってコミットされないことを最優先する。

---

Step 2: Worktree 作成

bash:

BRANCH_NAME="[type]/[description]-[issue-number]"
WORKTREE_NAME="${BRANCH_NAME//\//-}"
WORKTREE_PATH=".worktrees/${WORKTREE_NAME}"

git worktree add "${WORKTREE_PATH}" -b "${BRANCH_NAME}"

PowerShell:

$BranchName = "[type]/[description]-[issue-number]"
$WorktreeName = $BranchName -replace '/', '-'
$WorktreePath = ".worktrees/$WorktreeName"

git worktree add $WorktreePath -b $BranchName

既にブランチが存在する場合は -b を外して同じパスに追加する:

git worktree add "${WORKTREE_PATH}" "${BRANCH_NAME}"

作成後は対象 worktree に移動し、以降の変更はその中だけで行う。

---

Step 3: ポートレジストリ

worktree ごとのポートは、メインチェックアウト直下の .worktrees/.ports.json で管理する。

worktree 内からの相対パス（../.ports.json など）は worktree の配置に依存して壊れやすいため、メインチェックアウトで作成時に絶対パスを控えてエージェントへ渡す。

bash:

PORT_REGISTRY="$(pwd -P)/.worktrees/.ports.json"