mcpField
W
worktree-coordination

worktree-coordination

github.com/yonatangrossエージェントワークフロー29956 回インストール今日更新
リポジトリ

worktree-coordination について

worktree-coordination は、Git worktree で作業する複数の独立した Claude Code セッションを調整するスキルです。ファイルロック、インスタンス状態、競合チェック、共有の設計判断ログを提供します。

主な機能

  1. 01アクティブなインスタンスと worktree の追跡
  2. 02編集前のファイルロック
  3. 03コンテキスト同期と競合チェック
  4. 04設計判断の共有
  5. 05古いインスタンスとロックの整理

活用シーン

  1. 01複数セッションによる同一ファイルの編集防止
  2. 02コミット前の競合確認
  3. 03セッション間での設計判断の共有
  4. 04古い worktree セッションの特定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/yonatangross/orchestkit --skill worktree-coordination

インストール後、Claude Code で/worktree-coordinationを入力して読み込まれたか確認します。

詳細

Worktree Coordination Skill

CC 2.1.47 の Worktree 修正： Claude Code 2.1.47 では、worktree でスキル／エージェントが検出されない、worktree でバックグラウンドタスクが失敗する、Windows で worktree セッションが正しく照合されないという、3 つの重大な問題が解決されました。worktree は正式にサポートされるようになり、回避策は不要です。

Agent Teams（CC 2.1.33 以降）： CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が設定されている場合、ネイティブの Agent Teams に組み込みのチームメイトのライフサイクル管理、ピアツーピアのメッセージング、共有タスクリストが用意されています。このスキルのカスタムファイルロックと調整レジストリは、Teams のネイティブな調整機能に置き換えられます。このスキルは、Teams を使わない worktree のシナリオ（共有チームのない複数の独立した Claude Code セッションなど）でのみ使用してください。

ネイティブの Worktree サポート（CC 2.1.49）

CC 2.1.49 では、EnterWorktree ツールと --worktree (-w) CLI フラグを使ったネイティブの worktree 作成機能が追加されました：

# CLI flag — creates worktree and switches session into it
claude --worktree          # auto-named worktree
claude -w my-feature       # named worktree

# Tool — available to agents and skills
EnterWorktree(name="my-feature")  # creates .claude/worktrees/my-feature/

主な動作：

  • worktree は .claude/worktrees/ 内に、HEAD を基にした新しいブランチとともに作成されます
  • セッション終了時に、worktree を保持するか削除するかを尋ねられます
  • worktree でもスキル、エージェント、フックがすべて検出されます（CC 2.1.47 で修正）

ネイティブ機能とこのスキルの使い分け： 単一セッションの分離（手軽な機能ブランチなど）には EnterWorktree を使用してください。複数の Claude インスタンスでファイルロックと意思決定の共有が必要な複数セッションのシナリオでは、このスキルの調整レジストリを使用してください。

Worktree ライフサイクルフック（CC 2.1.50）

CC 2.1.50 では WorktreeCreate と WorktreeRemove のフックイベントが追加され、ライフサイクル管理を自動化できるようになりました：

  • WorktreeCreate：EnterWorktree または --worktree フラグで worktree が作成されたときに実行されます。自動登録や設定のコピーに使用します。
  • WorktreeRemove：worktree がクリーンアップされたときに実行されます。ロックのクリーンアップやレジストリの削除に使用します。

これらのフックがライフサイクル管理で推奨される方法です。ファイル監視による回避策に代わるものです。

エージェントの分離（CC 2.1.50）

エージェントは frontmatter に isolation: worktree を宣言することで、自動的に分離された worktree で実行できるようになりました：

isolation: worktree  # Agent gets its own worktree automatically

ファイルを変更するエージェントには、手動で EnterWorktree を呼び出すよりも、この方法が推奨されます。

コマンド

/worktree-status

アクティブなすべての Claude Code インスタンスのステータスを表示します。

使用方法： /worktree-status [--json] [--clean]

実行内容：

  1. cc-worktree-status を実行し、アクティブなすべてのインスタンスを確認します
  2. 古いインスタンス（ハートビートが 5 分以上ないもの）を確認します
  3. すべてのインスタンスのファイルロックを確認します

出力内容：

  • インスタンス ID とブランチ
  • 現在のタスク（設定されている場合）
  • 稼働状況（ACTIVE/STALE）
  • 各インスタンスがロックしているファイル
/worktree-claim

このインスタンスのためにファイルを明示的にロックします。

使用方法： /worktree-claim src/auth/login.ts

実行内容：

  1. ファイルがすでにロックされているか確認します
  2. 別のインスタンスがロックしている場合は、ロックしているインスタンスを表示します
  3. ロックされていない場合は、ロックを取得します
/worktree-release

ファイルのロックを解除します。

使用方法： /worktree-release src/auth/login.ts

/worktree-sync

共有コンテキストを同期し、競合を確認します。

使用方法： /worktree-sync [--check-conflicts] [--pull-decisions]

実行内容：

  1. --check-conflicts：他のアクティブなブランチに対して merge-tree を実行します
  2. --pull-decisions：他のインスタンスによる最近のアーキテクチャ上の決定を表示します
/worktree-decision

すべてのインスタンスから参照できるアーキテクチャ上の決定を記録します。

使用方法： /worktree-decision "Using Passport.js for OAuth" --rationale "Better middleware support"

自動動作

ファイルロック確認（PreToolUse フック）

Write または Edit 操作の前に：

  1. 別のインスタンスがファイルをロックしているか確認します
  2. ロックされている場合 → ロックしているインスタンスの詳細とともに BLOCK します
  3. ロックされていない場合 → ロックを取得して続行します
ハートビート（ライフサイクルフック）

30 秒ごと（worktree で確実に実行するには CC 2.1.47 以降が必要です）：

  1. このインスタンスのハートビートのタイムスタンプを更新します
  2. 古いインスタンス（ハートビートが 5 分以上ないもの）をクリーンアップします
  3. 孤立したロックを解除します
クリーンアップ（停止フック）

Claude Code の終了時（worktree で確実に実行するには CC 2.1.47+ が必要です）：

  1. このインスタンスが保持しているすべてのファイルロックを解放します
  2. 調整レジストリから登録を解除します

ファイルロックの状態

┌─────────────────────────────────────────────────────────┐
│  FILE: src/auth/oauth.ts                                │
├─────────────────────────────────────────────────────────┤
│  Status: LOCKED                                         │
│  Holder: cc-auth-a1b2c3                                 │
│  Branch: feature/user-authentication                    │
│  Task:   Implementing OAuth2 login flow                 │
│  Since:  2 minutes ago                                  │
├─────────────────────────────────────────────────────────┤
│  Action: Wait for release or use /worktree-release     │
└─────────────────────────────────────────────────────────┘

レジストリスキーマ

.claude/coordination/registry.json にあります：

{
  "instances": {
    "cc-auth-a1b2c3": {
      "worktree": "/Users/dev/worktrees/feature-auth",
      "branch": "feature/user-authentication",
      "task": "Implementing OAuth2",
      "files_locked": ["src/auth/oauth.ts"],
      "started": "-01-08T14:30:00Z",
      "last_heartbeat": "-01-08T14:45:32Z"
    }
  },
  "file_locks": {
    "src/auth/oauth.ts": {
      "instance_id": "cc-auth-a1b2c3",
      "acquired_at": "-01-08T14:35:00Z",
      "reason": "edit"
    }
  },
  "decisions_log": [
    {
      "id": "dec-001",
      "instance_id": "cc-auth-a1b2c3",
      "decision": "Use Passport.js for OAuth",
      "rationale": "Better middleware support",
      "timestamp": "-01-08T14:40:00Z"
    }
  ]
}

CLI コマンド

bin/ で利用できます：

# Create new coordinated worktree
cc-worktree-new <feature-name> [--base <branch>]

# Check status of all worktrees
cc-worktree-status [--json] [--clean]

# Sync context and check conflicts
cc-worktree-sync [--check-conflicts] [--pull-decisions]

ベストプラクティス

  1. worktree ごとに 1 つのタスク - 各 Claude Code インスタンスは、1 つの機能またはタスクに集中してください
  2. 早めにファイルを確保する - 共有ファイルの作業を始める前に、/worktree-claim を使用してください
  3. 決定事項を記録する - 他のインスタンスに影響する選択には、/worktree-decision を使用してください
  4. 競合を確認する - コミット前に cc-worktree-sync --check-conflicts を実行してください
  5. 後片付けをする - ロックを解放するため、Claude Code を適切に終了してください（Ctrl+C または /exit）

トラブルシューティング

「ファイルは別のインスタンスによってロックされています」
  1. 保持しているインスタンスを確認します：/worktree-status
  2. インスタンスが STALE の場合：cc-worktree-status --clean
  3. 正当に保持されている場合：他のインスタンスと調整するか、別のファイルで作業します
「インスタンスが登録されていません」

ハートビートフックは、最初のツール使用時に自動で登録します。問題が解決しない場合：

  1. CC 2.1.47+ を実行していることを確認します（worktree でのバックグラウンドタスクには、この修正が必要です）
  2. .claude-local/instance-id.txt が存在することを確認します
  3. .claude/coordination/ が正しくシンボリックリンクされていることを確認します

プラットフォームのサポート（CC 2.1.47+）

プラットフォームWorktree の状態備考
macOS完全サポートすべての機能がネイティブに動作します
Linux完全サポートすべての機能がネイティブに動作します
Windows完全サポートCC 2.1.47 では、ドライブ文字の大文字・小文字の違いによるセッションの照合が修正されました

worktree のサポートを改善する CC 2.1.47 の修正：

  • worktree からスキルとエージェントが正しく検出されるようになりました（以前はメインのチェックアウトからのみ検出されていました）
  • バックグラウンドタスク（Task ツール）が worktree から正常に完了するようになりました
  • Windows では、ドライブ文字の大文字・小文字の違いがあっても worktree セッションが照合されるようになりました

関連するスキル

  • ork:git-workflow - 各調整済み worktree 内で使用する Git ワークフローのパターン
  • ork:commit - 各 worktree で適切な規約形式のコミットを作成します
  • stacked-prs - 複数の worktree にまたがる可能性がある、依存関係のある PR を管理します
  • ork:architecture-decision-record - /worktree-decision で共有した決定事項を記録します

主な決定事項

決定事項選択理由
ロックの粒度ファイル単位競合防止と並行作業の柔軟性のバランスを取ります
古いインスタンスの検出ハートビートのタイムアウトは 5 分通常の一時停止には十分な長さで、迅速なクリーンアップには十分短い時間です
レジストリの場所.claude/coordination/シンボリックリンクを介して worktree 間で共有され、バージョン管理されます
ロックの取得Write/Edit 時に自動手動操作なしで、偶発的な競合を防ぎます
決定事項の共有一元化されたログすべてのインスタンスがアーキテクチャ上の決定をリアルタイムで確認できます

機能の詳細

status-check

キーワード： worktree、状態、インスタンス、アクティブ、誰 解決する内容：

  • すべてのアクティブな Claude Code インスタンスを確認する方法
  • どのファイルがロックされているかを確認する方法
  • 古いインスタンスを見つける方法
file-locking

キーワード： ロック、確保、解放、競合、ブロック 解決する内容：

  • インスタンス間のファイル競合を防ぐ方法
  • 編集前にファイルを確保する方法
  • 作業完了時にロックを解放する方法
decision-sync

キーワード： 決定事項、同期、共有、調整 解決する内容：

  • インスタンス間でアーキテクチャ上の決定を共有する方法
  • 他のインスタンスの決定事項を確認する方法
  • worktree 間で進め方を調整する方法
conflict-prevention

キーワード： 競合、マージ、重複、衝突 解決する内容：

  • コミット前にマージ競合を確認する方法
  • 作業の重複を避ける方法
  • 並行開発を調整する方法

コメント

Markdown 対応