Worktree Workflow

Worktree ワークフロー

ホスト環境での開発時に Git Worktree を使用してブランチを分離するワークフローです。

概要

用途: プラットフォーム固有コード（macOS API 等）の開発時に、container-use の代わりにホスト環境で作業する際のブランチ分離。

container-use vs worktree

Worktree のメリット

ディレクトリ構成

project/                         # メインworktree (main ブランチ)
├── .worktrees/                  # worktree 格納ディレクトリ
│   ├── issue-42-auth/           # feature/issue-42-auth ブランチ
│   │   ├── .env                 # ルートからコピー
│   │   └── ...
│   └── issue-43-dashboard/      # feature/issue-43-dashboard ブランチ
│       └── ...
└── .opencode/
    └── skill/
        ├── create-worktree/
        │   ├── SKILL.md
        │   ├── REFERENCE.md
        │   └── scripts/
        │       └── create_worktree.sh
        └── pr-and-cleanup/
            ├── SKILL.md
            ├── REFERENCE.md
            └── scripts/
                └── pr_and_cleanup.sh

基本フロー

Issue 受け取り → platform-exception? → YES → worktree 作成 → ホスト環境で開発 → CI で検証 → PR 作成 + worktree 削除 → マージ
                                    → NO  → container-use

コマンド

worktree 作成

bash .opencode/skill/create-worktree/scripts/create_worktree.sh issue-42-auth

実行結果:

• ブランチ: feature/issue-42-auth を作成
• ディレクトリ: .worktrees/issue-42-auth/ を作成
• 環境変数: .env 等を自動コピー

PR 作成 + worktree 削除

cd .worktrees/issue-42-auth
bash ../../.opencode/skill/pr-and-cleanup/scripts/pr_and_cleanup.sh

実行結果:

• PR を作成（インタラクティブ or 引数指定）
• worktree を削除
• main ブランチに戻る

オプション

# タイトル・本文を事前指定
bash ../../.opencode/skill/pr-and-cleanup/scripts/pr_and_cleanup.sh \
  --title "feat: Add macOS notification" \
  --body "Closes #42"

# ドラフト PR として作成
bash ../../.opencode/skill/pr-and-cleanup/scripts/pr_and_cleanup.sh --draft

# PR 作成のみ（worktree は残す）
bash ../../.opencode/skill/pr-and-cleanup/scripts/pr_and_cleanup.sh --pr-only

# worktree 削除のみ（PR 作成済みの場合）
bash ../../.opencode/skill/pr-and-cleanup/scripts/pr_and_cleanup.sh --cleanup-only

トラブルシューティング

worktree が既に存在する

git worktree list
git worktree remove .worktrees/<feature-name>

ブランチが既に存在する

スクリプトは既存ブランチを再利用します。新規ブランチを作成したい場合:

git branch -d feature/<feature-name>

未コミット変更がある

git status
git add . && git commit -m "WIP"
# または
git stash

命名規則

関連スキル

• create-worktree: worktree 作成の詳細
• pr-and-cleanup: PR 作成 + クリーンアップの詳細

関連ドキュメント

• platform-exception.md: 例外適用の判断基準
• container-use.md: 通常の実装ワークフロー