git-worktrees

Git Worktrees スキル

概要

並行開発タスク用に、分離された git worktree を作成、管理します。

トリガー

次の場合にこのスキルを有効にします：

• 複数のタスクを並行して実行できる
• ユーザーが並行処理可能なタスクで delegate を実行する
• サブエージェントの作業に分離された環境が必要
• ユーザーが worktree のセットアップを明示的に依頼する

Worktree ディレクトリの場所

優先順位：

1. .worktrees/ — 存在し、gitignore されている場合
2. worktrees/ — 存在し、gitignore されている場合
3. プロジェクトの規約について CLAUDE.md を確認する
4. 不明な場合はユーザーに確認する

安全性チェック（必須）：

# Verify directory is gitignored before creating
git check-ignore -q .worktrees && echo "Safe" || echo "NOT GITIGNORED"

gitignore されていない場合は、.gitignore に追加します：

.worktrees/

Worktree のライフサイクル

1. Worktree を作成する

# Create feature branch
git branch feature/task-name main

# Create worktree
git worktree add .worktrees/task-name feature/task-name

# Verify creation
git worktree list

命名規則： .worktrees/<task-id>-<brief-name>

• 例：.worktrees/001-user-auth
• 例：.worktrees/002-api-endpoints

2. 環境をセットアップする

プロジェクトの種類ごとの環境セットアップ表とスクリプトの全容については、references/commands-reference.md を参照してください。

3. ベースラインを検証する

worktree の準備ができていることを確認するため、ベースラインテストを実行します：

exarchos_orchestrate({
  action: "verify_worktree_baseline",
  worktreePath: ".worktrees/task-name"
})

このスクリプトはプロジェクトの種類（Node.js、.NET、Rust）を自動検出し、適切なテストコマンドを実行します。

passed: true の場合： ベースラインテストに合格しました。worktree は実装を開始できる状態です。 passed: false の場合： ベースラインテストに失敗したか、プロジェクトの種類が不明です。続行する前に調査してください。

ベースラインテストに失敗した場合：

1. main ブランチのテストが失敗しているか確認する
2. 問題をユーザーに報告する
3. 実装を続行しない

4. Worktree で作業する

サブエージェントは worktree ディレクトリで作業します：

• 他のタスクから完全に分離されます
• コミットは機能ブランチに反映されます
• テストを個別に実行できます

5. マージ後にクリーンアップする

# After PR merged, remove worktree
git worktree remove .worktrees/task-name

# Optionally delete branch
git branch -d feature/task-name

# Prune stale worktree refs
git worktree prune

並行 Worktree の管理

並行 worktree の作成例、追跡形式、コマンドリファレンス表の全容については、references/commands-reference.md を参照してください。

Worktree の検証

検証が必要な理由

サブエージェントは、変更を加える前に必ず worktree 内にいることを確認する必要があります。メインプロジェクトのルートで作業すると、次の問題が発生します：

• 並行タスク間でマージコンフリクトが発生する
• 共有状態を誤って変更する
• ビルドやテストが互いに干渉する

Worktree の確認

ファイルを変更する前に、worktree 検証スクリプトを実行します：

exarchos_orchestrate({
  action: "verify_worktree"
})

現在のディレクトリではなく、指定したパスを確認するには：

exarchos_orchestrate({
  action: "verify_worktree",
  cwd: "/path/to/.worktrees/task-name"
})

passed: true の場合： 有効な worktree 内にいます。実装を進めてください。 passed: false の場合： worktree 内ではありません。直ちに停止し、ファイルを変更しないでください。

サブエージェントへの指示

すべての実装担当者向けプロンプトに、次の内容を含めます：

## CRITICAL: Worktree Verification (MANDATORY)

Before making ANY file changes, run:

    exarchos_orchestrate({ action: "verify_worktree" })

If `passed: false`: STOP and report error.
DO NOT proceed with any modifications outside a worktree.

アンチパターン

してはいけないこと	代わりにすること
管理対象のディレクトリに worktree を作成する	gitignore された .worktrees/ を使う
ベースラインテストの検証を省略する	必ず最初にテストの合格を確認する
古い worktree を放置する	マージ後にクリーンアップする
依存関係のインストールを忘れる	各 worktree でプロジェクトをセットアップする
worktree をまたいで作業を混在させる	1 つの worktree につき 1 つのタスクにする

委任との連携

委任スキルが並行タスクを起動する場合：

1. 並行グループごとに worktree を作成する
2. 環境をセットアップする
3. ベースラインテストを検証する
4. worktree のパスを指定してサブエージェントに指示を出す
5. 進捗を追跡する
6. 依存関係の順序に従ってブランチをマージする
7. worktree をクリーンアップする

マージ待ちの引き継ぎ

サブエージェントが作業ツリーでタスクを完了すると、ワークフローの HSM は delegate から feature/merge-pending に遷移します。統合ブランチは共有されており、兄弟作業ツリーのマージが競合する可能性があるため、serialize_merge が統合マージの経路になります。これは integrationRef ごとの単一ライターリースを保持したうえで、merge_orchestrate を組み合わせ、記録されたリカバリポイント SHA を使ったローカルの git merge により、作業ツリーのブランチを統合ブランチに取り込みます。引き継ぎプロトコルの全容については、@skills/merge-orchestrator/SKILL.md を参照してください。この統合マージに生の merge_orchestrate をディスパッチしないでください（有効な他者のリースがあるとフェイルクローズします）。生の merge_orchestrate は、統合以外のマージ、またはクラッシュ後に元のリースを再提示する呼び出し元向けです。

作業ツリーのクリーンアップ（上記のステップ 7）は、マージから phase: 'completed' が報告された後に実行します。

これは、synthesize フェーズで行うリモート PR のマージ（merge_pr）とは異なります。serialize_merge／merge_orchestrate はメインの作業ツリーにあるローカル参照を操作します。merge_pr は、統合ブランチの準備が整った後、人間によるレビュー用の PR に向けて VCS プロバイダーを呼び出します。

完了条件

作業ツリーのセットアップの場合：

• ディレクトリが gitignore に登録されている
• 作業ツリーが正常に作成されている
• 環境の依存関係がインストールされている
• ベースラインテストが合格している
• サブエージェントの作業を開始できる状態になっている

作業ツリーのクリーンアップの場合：

• フィーチャーブランチが main にマージされている
• 作業ツリーが削除されている
• ブランチが削除されている（マージ済みの場合）
• 古い参照が整理されている