Git Worktree 概要

Git Worktree は MoAI-ADK で並列開発を行うための中核機能です。各 SPEC を独立した環境で開発できるように完全な分離を提供します。

なぜ Worktree が必要なのか

問題点: LLM 設定の共有

従来の MoAI-ADK では moai glm または moai cc コマンドで LLM を変更すると、すべての開かれたセッションに同じ LLM が適用されます。これにより以下の問題が発生します:

• SPEC 間の干渉: 別の SPEC を開発する際に LLM 設定が互いに影響する
• 並列開発不可: 同時に複数の SPEC を開発できない
• コスト効率の低下: すべてのセッションで高コストの Opus を使用する必要がある

解決策: 完全な分離

Git Worktree を使用すると、各 SPEC が完全に独立した Git 状態と LLM 設定を維持します:

コアワークフロー

3段階開発プロセス

Git Worktree を活用した MoAI-ADK 開発は 3 段階で構成されます:

段階別詳細説明

1段階: Plan (Terminal 1)

Claude 4.5 Opus を使用して SPEC ドキュメントを作成します:

> /moai plan "認証システム追加" --worktree

作業内容:

• EARS 形式の SPEC ドキュメント自動作成
• 該当 SPEC 用の Worktree 自動作成
• Feature ブランチ自動作成と切り替え

成果物:

• .moai/specs/SPEC-AUTH-001/spec.md
• 新しい Worktree ディレクトリ
• feature/SPEC-AUTH-001 ブランチ

2段階: Implement (Terminals 2, 3, 4…)

GLM 5 またはその他のコスト効率の良いモデルを使用して実装します:

# Worktree に入る (新しいターミナル)
$ moai worktree go SPEC-AUTH-001
 
# LLM 変更
$ moai glm
 
# 開発開始
$ claude
> /moai run SPEC-AUTH-001
> /moai sync SPEC-AUTH-001

利点:

• 完全に分離された作業環境
• GLM コスト効率 (Opus 比 70% 節減)
• 衝突のない無制限並列開発

3段階: Merge & Cleanup

moai worktree done SPEC-AUTH-001              # main → マージ → クリーンアップ
moai worktree done SPEC-AUTH-001 --push       # 上記作業 + リモートリポジトリにプッシュ

Worktree コマンドリファレンス

Worktree の核心的な利点

1. 完全な分離 (Complete Isolation)

各 SPEC は独立した Git 状態を維持します:

利点:

• 各 Worktree で独立してコミット可能
• ブランチ間の衝突なしで作業
• 完了した SPEC のみ main にマージ

2. LLM 独立性 (LLM Independence)

各 Worktree は別個の LLM 設定を維持します:

3. 無制限並列開発 (Unlimited Parallel)

同時に複数の SPEC を開発できます:

# Terminal 1: SPEC-AUTH-001 計画
> /moai plan "認証システム" --worktree
 
# Terminal 2: SPEC-AUTH-002 実装 (GLM)
$ moai worktree go SPEC-AUTH-002
$ moai glm
> /moai run SPEC-AUTH-002
 
# Terminal 3: SPEC-AUTH-003 実装 (GLM)
$ moai worktree go SPEC-AUTH-003
$ moai glm
> /moai run SPEC-AUTH-003
 
# Terminal 4: SPEC-AUTH-004 ドキュメント化
$ moai worktree go SPEC-AUTH-004
> /moai sync SPEC-AUTH-004

4. 安全なマージ (Safe Merge)

完了した SPEC のみ main ブランチにマージされます:

並列開発の視覚化

複数のターミナルで同時に作業する様子:

次のステップ

• 完全ガイド - Git Worktree のすべてのコマンドと詳細な使用方法
• 実際の使用例 - 実際のプロジェクトでの使用事例
• よくある質問 - FAQ および問題解決

関連ドキュメント

• MoAI-ADK ドキュメント 
• SPEC システム
• DDD ワークフロー