moai-workflow-worktree

MoAI Worktree 管理

並列 SPEC 開発のための Git worktree 管理システムです。分離されたワークスペース、自動登録、シームレスな MoAI-ADK 統合を実現します。

基本方針：コンテキスト切り替えの負担なく真の並列開発を実現するため、各 SPEC に専用の分離されたワークスペースを用意します。

クイックリファレンス（30 秒）

MoAI Worktree 管理とは？ 各 SPEC 用に分離された開発環境を作成し、競合のない並列開発を可能にする専用の Git worktree システムです。

主な機能：

• 分離されたワークスペース：各 SPEC に独立した Git の状態を持つ専用の worktree が割り当てられます
• 自動登録：worktree レジストリが、すべてのアクティブなワークスペースを追跡します
• 並列開発：複数の SPEC を同時に開発できます
• シームレスな統合：/moai plan、/moai run、/moai sync のワークフローで動作します
• スマートな同期：必要に応じてベースブランチと自動同期します
• クリーンアップの自動化：マージ済みの worktree を自動的にクリーンアップします

すぐに参照：

• CLI コマンド：modules/worktree-commands.md の Worktree Commands Module を参照してください
• 管理パターン：modules/worktree-management.md の Worktree Management Module を参照してください
• 並列ワークフロー：modules/parallel-development.md の Parallel Development Module を参照してください
• 統合ガイド：modules/integration-patterns.md の Integration Patterns Module を参照してください
• トラブルシューティング：modules/troubleshooting.md の Troubleshooting Module を参照してください

使用例：

• 複数の SPEC の並列開発
• 分離されたテスト環境
• フィーチャーブランチの分離
• コードレビューのワークフロー
• 実験的な機能の開発

---

実装ガイド（5 分）

1. コアアーキテクチャ - Worktree 管理システム

目的：並列 SPEC 開発用に分離された Git worktree を作成します。

主なコンポーネント：

1. Worktree Registry - すべての worktree を追跡する一元管理レジストリ
2. Manager Layer - 作成、切り替え、削除、同期を含む worktree の中核操作
3. CLI Interface - 使いやすいコマンドインターフェース
4. Models - worktree メタデータ用のデータ構造
5. Integration Layer - MoAI-ADK ワークフロー統合

レジストリの構造：

レジストリファイルには worktree のメタデータが JSON 形式で保存されます。各 worktree エントリーには、識別子、ファイルパス、ブランチ名、作成タイムスタンプ、最終同期時刻、ステータス（アクティブまたはマージ済み）、ベースブランチの参照が含まれます。config セクションでは、worktree のルートディレクトリ、自動同期の設定、マージ済みブランチのクリーンアップ動作を定義します。

ファイル構成：

worktree システムは、ユーザーのグローバルホームディレクトリに専用のディレクトリ構成を作成します。moai worktree new <name> で作成されたツリーは、ホームのプロジェクトルート（/worktrees/projects///）に配置されます。L2 永続レジストリは引き続き worktree ルート（~/.moai/worktrees/{ProjectName}/）にあり、ここには一元管理用のレジストリ JSON ファイルと、各 SPEC 用の個別ディレクトリがあります。各 SPEC ディレクトリには、worktree のメタデータを格納する .git ファイルと、プロジェクトファイルの完全なコピーが含まれます。

詳細なリファレンス：modules/worktree-management.md の Worktree Management Module を参照してください

---

2. CLI コマンド - 完全なコマンドインターフェース

目的：各 worktree タスクを、実際にそのタスクを実行するコマンドに対応付けます。

worktree に入るのはランチャーの役割です。moai worktree に作成用の動詞はありません。

• moai cc -w <name> — worktree 内で作業します
• moai cc -w <name> --spawn — 現在のセッションを維持したまま、新しい tmux ウィンドウで開きます

確認には、git を直接使用します：git worktree list。

管理コマンドは、moai worktree --help に記載されています。

コマンド	目的
sync [branch-name]	worktree をベースブランチと同期します
remove [path]	worktree を削除します
clean	古い worktree 参照をクリーンアップします
recover	worktree レジストリを修復します
done [branch-name]	worktree を完了し、クリーンアップします
snapshot	ガード検証用に作業ツリーの状態のスナップショットを取得します
verify	スナップショットと照合して作業ツリーの状態を検証し、エージェントの応答を確認します
restore	作業ツリーをスナップショットの HEAD の状態に復元します

この表はヘルプ出力をそのまま転記したものです。正式な一覧は moai worktree --help です。両者に違いがある場合は、ヘルプ出力が優先されます。

詳細なリファレンス：Worktree Commands モジュール（modules/worktree-commands.md）を参照してください。そこに記載されているコマンド例は現在のコマンドセットより前のものです。上の表と異なる場合は、表と moai worktree --help が優先されます。

---

3. 並列開発ワークフロー - SPEC を分離した開発

目的：コンテキストを切り替えることなく、真の並列開発を可能にします。

ワークフローとの統合：

Plan フェーズで /moai plan を使用すると、SPEC が作成され、ランチャー（moai cc -w <name>）がその SPEC 用の分離された worktree に入ります。

Development フェーズでは、分離された worktree 環境により、コンテキスト切り替えのオーバーヘッドなしに、独立した Git 状態が提供されます。

Sync フェーズで /moai sync を使用すると、worktree の sync コマンドによって、コンフリクト解決をサポートしながらクリーンに統合できます。

Cleanup フェーズでは、worktree の clean コマンドによって、レジストリを維持しながら自動的にクリーンアップできます。

並列開発のメリット：

1. コンテキストの分離：各 SPEC に固有の Git 状態、ファイル、環境があります
2. 切り替えコストゼロ：worktree 間を即座に切り替えられます
3. 独立した開発：複数の SPEC を同時に作業できます
4. 安全な実験：実験的な機能向けの分離された環境を利用できます
5. クリーンな統合：同期とコンフリクト解決を自動で行います

ワークフローの例：

まず、「User Authentication」のような説明を付けて SPEC-001 用の worktree を作成し、そのディレクトリに切り替えます。次に、/moai run SPEC-001 を実行して分離環境で開発します。その後、メインリポジトリに戻り、「Payment Integration」という説明を付けて SPEC-002 用の別の worktree を作成します。その worktree に切り替えて、/moai run SPEC-002 を実行し、並列で開発します。必要に応じて worktree 間を切り替えながら開発を続けます。最後に、統合の準備ができたら両方の worktree を同期します。

詳細なリファレンス：Parallel Development モジュール（modules/parallel-development.md）を参照してください。

---

4. 統合パターン - MoAI-ADK ワークフローとの統合

目的：MoAI-ADK の Plan-Run-Sync ワークフローとシームレスに統合します。

統合ポイント：

Plan フェーズでは、/moai plan との統合により、SPEC の作成後、ランチャーを使って worktree に入ります。moai cc -w <name> はその中で動作し、moai cc -w <name> --spawn は新しい tmux ウィンドウで開きます。

開発フェーズでは、/moai run を使用します。worktree による分離でクリーンな開発環境が提供され、独立した Git の状態によって競合を防ぎ、自動的にレジストリが追跡されます。

Sync フェーズでは、/moai sync を使用します。PR を作成する前に、SPEC の sync コマンドを実行します。PR のマージ後、マージ済みのみを対象にするフラグを指定して clean コマンドを実行し、完了した worktree を削除します。

自動検出パターン：

システムは、親ディレクトリにあるレジストリファイルを確認して worktree 環境を検出します。検出されると、現在のディレクトリ名から SPEC ID が抽出されます。

設定との統合：

MoAI の設定では、worktree の設定をサポートしています。自動的に worktree を作成する auto_create、自動同期を行う auto_sync、マージ済みブランチを自動的にクリーンアップする cleanup_merged、プロジェクト名を置換して worktree ディレクトリの場所を指定する worktree_root があります。

詳細なリファレンス：modules/integration-patterns.md の統合パターンモジュールを参照してください。

---

5. --spawn — 新しい tmux ウィンドウでチームメイトのセッションを起動

目的：現在のセッションを終了せずに、worktree で Claude または GLM のセッションを開始します。

起動コマンド（moai cc、moai glm）は通常、実行中のシェルを置き換えます。「ここで今すぐ作業する」場合には適切ですが、「作業を続けながらチームメイトも同時に起動する」という使い方はできません。代わりに --spawn は同じコマンドを新しい tmux ウィンドウで再実行し、呼び出し元に戻るため、作業を続けられます。

-w <name> と組み合わせると、1 つのコマンドで分離された worktree にチームメイトを起動できます。

moai glm -w feat-auth --spawn   # Explicit all-GLM session in .claude/worktrees/feat-auth
moai cc -w feat-auth --spawn    # Claude teammate, same worktree
moai glm -w feat-auth --spawn   # all-GLM teammate

動作：

• 新しいウィンドウはデタッチ状態で作成されるため、フォーカスは呼び出し元のペインに留まります。表示されるペイン ID（例：%7）を使って、そのウィンドウに切り替えられます。
• 起動されたウィンドウはプロジェクトルートから開始されるため、短い -w <name> の値は .claude/worktrees/<name>/ に対して解決されます（<MoaiHome>/worktrees/projects/<project-key> に同じ名前の既存のツリーがある場合は、そこに再度入ります）。
• --spawn は MoAI によって消費され、Claude Code には渡されません。-- パススルーマーカーの後にある引数はそのまま維持されます。
• 引数はシェル用に引用符で囲まれるため、スペースやシェルメタ文字を含む worktree 名も、変更されずに起動されたプロセスに渡されます。

要件 — 呼び出し元のセッションを置き換えてしまうサイレントフォールバックは、--spawn の目的そのものに反するため、以下のいずれかを満たさない場合は、明確なエラーを表示して処理を拒否します。

不足項目	メッセージ
$TMUX（セッション内にいない）	tmux session required for --spawn
tmux バイナリ	--spawn requires the tmux binary
PATH 内の moai バイナリ	--spawn needs the moai binary in PATH

これらのチェックが実行される前に設定が変更されることはないため、処理が拒否されても環境はそのままです。起動されたコマンドは、新しいウィンドウ内で独自にバックエンドを設定します。

プラットフォームに関する注意：tmux は POSIX 専用のため、--spawn は Windows では使用できず、バイナリが見つからないことを示すエラーが報告されます。-w を使ってその場で worktree に入る機能は、すべてのプラットフォームで動作します。

詳細なリファレンス：ランチャーの spawn エントリーポイント — フラグの除去、シェル用の引用符を使ったコマンドの再構築、tmux ウィンドウの呼び出し。

---

高度な実装（10 分以上）

同期戦略

moai worktree sync はデフォルトでベースブランチを worktree にマージします。--strategy rebase を指定すると、代わりに worktree をベースブランチの上にリベースし、--base でベースブランチを選択します。同期が競合で停止した場合は、worktree 内で通常の git コマンドを使って競合を解決し、同期を再実行してください。

提供されない機能

moai worktree には、共有またはチームのレジストリモード、開発者ごとのプレフィックス、選択的な同期パターン、競合の自動解決や対話モード、ワークツリーテンプレート、浅いクローン、バックグラウンド、並列、キャッシュの各オプションはありません。ワークツリーに入ってから準備を行い、利用可能なフラグについては modules/worktree-commands.md を参照してください。

---

相性のよい機能

コマンド：

• /moai plan - ワークツリーの自動セットアップを伴う SPEC の作成
• /moai run - 分離されたワークツリー環境での開発
• /moai sync - ワークツリーの自動同期との統合
• /moai feedback - ワークツリーワークフローの改善

スキル：

• moai-foundation-core - 並列開発パターン
• moai-workflow-project - プロジェクト管理との統合
• moai-workflow-spec - SPEC 駆動開発
• moai-ref-git-workflow - Git ワークフローの最適化

ツール：

• Git worktree - Git ネイティブのワークツリー機能
• Cobra - CLI コマンドのフレームワークと整形済み出力

---

簡単な判断ガイド

新しい SPEC の開発では、自動セットアップを伴うワークツリー分離パターンを使用します。主なアプローチはワークツリー分離で、補助パターンは /moai plan との統合です。

複数の SPEC を並行して開発する場合は、SPEC ごとに 1 つのワークツリーと 1 つのセッションを使用します。主なアプローチは複数のワークツリーを維持することで、補助パターンはそれぞれを専用の tmux ウィンドウで moai cc -w <name> --spawn を使って開くことです。

チームで連携する場合は、各開発者に専用のワークツリーとブランチを用意します。主なアプローチは開発者ごとの分離で、補助パターンはベースブランチとプルリクエストを通じて統合することです。

コードレビューのワークフローでは、レビュー用に分離されたワークツリーを使用します。主なアプローチはレビューでのワークツリー分離で、補助パターンはレビュー完了後にクリーンな状態で同期することです。

実験的な機能では、自動クリーンアップを伴う一時的なワークツリーを使用します。主なアプローチは一時的なワークツリーの作成で、補助パターンは自動削除による安全な実験です。

モジュール別の詳細：

• Worktree Commands：完全な CLI リファレンスについては modules/worktree-commands.md を参照してください
• Worktree Management：コアアーキテクチャについては modules/worktree-management.md を参照してください
• Parallel Development：ワークフローパターンについては modules/parallel-development.md を参照してください
• Integration Patterns：MoAI-ADK との統合については modules/integration-patterns.md を参照してください
• Troubleshooting：問題の解決については modules/troubleshooting.md を参照してください

完全な例：references/examples.md を参照してください 外部リソース：references/reference.md を参照してください

よくある合理化

合理化	実際のところ
"この小さな変更にワークツリー分離は大げさだ"	並行作業中に main で小さな変更を行うと、マージ競合が発生します。ワークツリーを使えばこれを防げます。
"main ブランチで作業すればよい。そちらのほうが速い"	main で作業すると、ほかのエージェントによる書き込みが妨げられます。ワークツリーを使えば並行作業が可能になります。
"読み取り専用エージェントにも安全のためにワークツリー分離が必要だ"	エージェントが使用するツールの一覧に、書き込み可能なツールが一切ない場合に限り、分離は不要です。起動時のモードパラメーターは非推奨で無視されるため、何もブロックしません。Write、Edit、NotebookEdit を省くだけでは不十分です。Bash はシェル経由で書き込みを行い、ほかのファイル変更ツール（別のシェル、MCP ツール、または書き込みを行うエージェントを起動する Agent）も同様です。そのようなツールが存在する限り、読み取り専用は保証されず、分離は無駄ではありません。
"ワークツリーのクリーンアップは省略してもよい。git が処理してくれる"	古いワークツリーのブランチが蓄積し、git worktree list が分かりにくくなります。使用後は必ず prune を実行してください。
"ワークツリーの構成は同じだから、エージェントのプロンプトに絶対パスを使っても問題ない"	メインリポジトリへの絶対パスを使うと、ワークツリーの分離が完全に無効になります。相対パスを使用してください。

危険信号

• 分離なしで実装エージェントを起動している：チームモードで worktree を使用している
• 書き込み可能なツールを1つも持たないツールリストのエージェントを、分離ありで起動している：worktree（不要なオーバーヘッド）
• エージェントのプロンプトに、書き込み先としてメインプロジェクトディレクトリの絶対パスが含まれている
• チームセッション完了後に worktree が削除されていない（古いブランチが残っている）
• worktree で分離されたエージェントのプロンプト内の Bash コマンドで cd /absolute/project/path を実行している

検証

• 実装担当のチームメイトが分離ありで起動されている：worktree（エージェントの起動パラメーターを確認）
• 分離なしで起動されたチームメイトが、書き込み可能なツールを持っていない（Write、Edit、NotebookEdit、Bash、およびその他のファイルを変更するツールがあるかツールリストを確認。いずれかが存在する場合、読み取り専用であることは保証されません）
• エージェントのプロンプトでは、書き込み対象ファイルを相対パスのみで指定している
• セッション終了後、git worktree list に古い worktree が表示されない
• Claude Code >= 2.1.97 で worktree の CWD 分離を検証済み（バージョンを確認）
• フックスクリプト（handle-worktree-create.sh、handle-worktree-remove.sh）が存在し、実行可能になっている