Git Worktreeによる並列タスク

.worktrees/ に最新のメインから分岐した独立したワークツリーを作成し、スペック ディレクトリをスキャフォルディングします。

使用するとき

• 現在の作業をブロックしたり、依存しない独立したタスクに取り組む場合
• 現在のブランチの進行中の変更から分離する必要がある場合
• 長いビルド/テストを実行しながら他の作業を続ける場合

ワークフロー

digraph parallel_task {
    rankdir=TB;
    node [shape=box];

    start [label="Start" shape=ellipse];
    get_desc [label="User provides high-level\ntask description"];
    derive [label="Derive dir name, branch name,\nand feature name from description"];
    create_wt [label="create-worktree.sh\n<dir-name> <branch-name>"];
    install [label="pnpm install in worktree"];
    init_spec [label="Run init-feature.sh\ninside worktree"];
    fix_yaml [label="Patch feature.yaml\nwith correct branch name"];
    fill_spec [label="Fill spec.md with\nrequirements (if provided)"];
    commit [label="git add + commit\nspec scaffold"];
    open_editor [label="Open editor in worktree"];
    success [label="Report: editor opening..." shape=ellipse];
    fail [label="Report: manual instructions" shape=ellipse];

    start -> get_desc;
    get_desc -> derive;
    derive -> create_wt;
    create_wt -> install;
    install -> init_spec;
    init_spec -> fix_yaml;
    fix_yaml -> fill_spec;
    fill_spec -> commit;
    commit -> open_editor;
    open_editor -> success [label="success"];
    open_editor -> fail [label="fail"];
}

ステップ

1. タスク説明を取得する

ユーザーが並列タスクについての高レベルな説明を提供します。

例：

• 「設定画面のバージョン表示バグを修正」
• 「エージェント HTTP呼び出しに再試行ロジックを追加」
• 「DIコンテナの登録をリファクタリング」

2. 名前を導出する

説明から以下を生成します：

• ディレクトリ名: ワークツリー ディレクトリの短いケバブケース識別子（例：fix-version-display, add-agent-retry, refactor-di-container）
• ブランチ名: プロジェクトのプリフィックス規約を使用した従来型ブランチ名（例：fix/version-display, feat/agent-retry, refactor/di-container）
• フィーチャー名: スペック ディレクトリ用のケバブケース名（ディレクトリ名と同じか調整済み）

適切なプリフィックスを使用してください：feat/, fix/, refactor/, chore/, docs/ など

3. ワークツリーを作成する

.claude/skills/shipit-kit-parallel-task/scripts/create-worktree.sh "<dir-name>" "<branch-name>"

このスクリプトは最新のメインを取得し、.worktrees/<dir-name> にワークツリーを作成し、origin/main に基づいて <branch-name> ブランチを作成します。

4. 依存関係をインストールする

cd .worktrees/<dir-name> && pnpm install

5. スペック ディレクトリを初期化する

次のスペック番号を決定し、ワークツリー内で 既存の初期化スクリプトを実行します：

cd .worktrees/<dir-name>

# 次のスペック番号を決定
NEXT_NUM=$(ls -d specs/[0-9][0-9][0-9]-* 2>/dev/null | wc -l | xargs -I{} printf "%03d" $(({} + 1)))
[ -z "$NEXT_NUM" ] && NEXT_NUM="001"

# init-feature.sh を実行（shipit-kit:new-feature テンプレートを再利用）
.claude/skills/shipit-kit-new-feature/scripts/init-feature.sh "$NEXT_NUM" "<feature-name>"

6. feature.yamlにパッチを当てる

初期化スクリプトは branch: feat/NNN-feature-name を設定しますが、実際のブランチは異なります。修正してください：

# feature.yaml のブランチ名を実際のワークツリー ブランチ名に変更
sed -i "s|branch: 'feat/.*'|branch: '<branch-name>'|" specs/NNN-feature-name/feature.yaml

7. spec.md を埋める（要件が提供されている場合）

ユーザーが十分なコンテキストを含む説明を提供した場合、spec.md を埋めます：

• 問題ステートメント（ユーザーの説明から）
• 成功基準（スコープから推論）
• 影響を受けるエリア（コードベース分析から）
• 理由付きのサイズ見積もり

それ以外の場合は、テンプレートプレースホルダーを手動での埋め込み用に残します。

8. スペック スキャフォルドをコミットする

cd .worktrees/<dir-name>
git add specs/
git commit -m "feat(specs): add NNN-feature-name specification"

9. エディターを開く・ハンドオフ（ここで終了します）

重要：実装を開始しないでください。/shipit-kit:research, /shipit-kit:plan, または /shipit-kit:implement を実行しないでください。

エディターを自動で開く： $TERM_PROGRAM から現在の実行コンテキストを検出し、一致するエディターでワークツリーを開きます：

• $TERM_PROGRAM が vscode の場合 → code を使用
• $TERM_PROGRAM が cursor の場合 → cursor を使用
• それ以外 → code を試し、次に cursor にフォールバック

if [ "$TERM_PROGRAM" = "vscode" ]; then
  code .worktrees/<dir-name>
elif [ "$TERM_PROGRAM" = "cursor" ]; then
  cursor .worktrees/<dir-name>
else
  code .worktrees/<dir-name> || cursor .worktrees/<dir-name>
fi

コマンドが成功した場合、以下を印刷します：

---

ワークツリーの準備ができました！エディターで開いています...

詳細	値
ワークツリー	.worktrees/<dir-name>
ブランチ	<branch-name> (origin/main に基づく)
スペック	specs/NNN-feature-name/

新しいエディター ウィンドウが開きます。読み込みが完了したら、AIエージェント パネルを開き、/shipit-kit:research で続行してください。

ワークツリー内で作業することで、現在のセッションを自由に保ちながら、新しいセッションにフィーチャー用の完全なコンテキストを与えることができます。

---

両方のコマンドが失敗した場合 （インストールされていない、PATH に含まれていない場合など）、手動の手順の印刷にフォールバックします：

---

ワークツリーの準備ができました！

詳細	値
ワークツリー	.worktrees/<dir-name>
ブランチ	<branch-name> (origin/main に基づく)
スペック	specs/NNN-feature-name/

エディターを自動で開くことができませんでした。手動で開いてください：

オプション A — エディター （推奨）

1. 新しいエディター ウィンドウ を開きます（Cursor、VS Code など）
2. File → Open Folder… → .worktrees/<dir-name> を選択
3. AIエージェント パネルを開き、/shipit-kit:research で続行してください

オプション B — ターミナル

cd .worktrees/<dir-name>
claude
# その後、/shipit-kit:research を実行

ワークツリー内で作業することで、現在のセッションを自由に保ちながら、新しいセッションにフィーチャー用の完全なコンテキストを与えることができます。

---

上記のメッセージを印刷した後、停止してください。さらなるアクションを取らないでください。

クリーンアップ

並列タスク完了時：

# ワークツリーを削除
git worktree remove .worktrees/<dir-name>

# ブランチを削除（マージ済みまたは不要な場合）
git branch -d <branch-name>

# または、古いワークツリー エントリをプルーニング
git worktree prune

クイック リファレンス

コマンド	目的
git worktree add <path> -b <branch> origin/main	メインからワークツリーを作成
git worktree list	すべてのワークツリーをリスト表示
git worktree remove .worktrees/<name>	ワークツリーを削除
git worktree prune	古いエントリをクリーンアップ
git branch -d <branch>	マージ済みブランチを削除

よくある間違い

依存関係のインストールを忘れる

• 問題： ワークツリーは Git オブジェクトを共有しますが、node_modules は共有しません
• 修正： 新しいワークツリーで常に pnpm install を実行してください

ワークツリーのクリーンアップを忘れる

• 問題： 古いワークツリーが .worktrees/ に蓄積します
• 修正： タスク完了時にワークツリーを削除し、ブランチを削除してください

ブランチ名の衝突

• 問題： 既に存在するブランチ名を再利用する
• 修正： スクリプトは既存のブランチをチェックし、必要に応じてタイムスタンプを付加します

feature.yaml の間違ったブランチ

• 問題： init-feature.sh は branch: feat/NNN-name を設定しますが、ワークツリーは別のブランチを使用します
• 修正： 初期化スクリプトを実行した後、常に feature.yaml にパッチを当ててください（ステップ 6）