Git Worktree 概要

情報

所属バリュー: エージェンティック・ハーネス

Git Worktree は MoAI-ADK 並列開発の土台です。SPEC ごとに完全に独立した作業 空間を作り、異なる Git 状態と異なる LLM 設定を同時に保てるようにしてくれます。

プラットフォームの基礎

プラットフォーム層の背景については ワークツリー を参照してください。MoAI-ADK としての説明はこのページです。

3 つの核心のうち エージェンティック・ハーネス (品質統制) の側から見ると、Worktree は SPEC ごとに作業空間を完全に分ける統制装置です。エージェントが並列に動いても互いの作業を 上書きせず、完了した SPEC だけが main へマージされることを保証します。コスト (トークノミクス) 面の利点も後からついてきます。worktree ごとに LLM 実行モードを個別に 指定できるので、計画ターミナルでは推論の強い Claude モデルを、実装ターミナルでは低コストの GLM を使うというように、ステップごとにモデルを振り分けられます。

Worktree なしに moai glm や moai cc で LLM バックエンドを変えると、同じプロジェクトで 開いているすべてのセッションに同じ設定がかかります。その結果:

• SPEC 間の干渉 — ある SPEC で変えた LLM 設定が別の SPEC の作業まで揺さぶります
• 並列開発が不可能 — 複数の SPEC を異なる条件で同時に進められません
• トークンの浪費 — 単純な実装作業まですべて高コストのモデルで回ります

Git Worktree を使うと、SPEC ごとに Git 状態と LLM 設定が互いに独立して動きます:

graph TD
    A[Main Repository] --> B[Worktree 1
SPEC-AUTH-001
Claude Opus]
    A --> C[Worktree 2
SPEC-AUTH-002
GLM 5]
    A --> D[Worktree 3
SPEC-AUTH-003
Claude Sonnet]

    B --> E[独立した作業]
    C --> F[独立した作業]
    D --> G[独立した作業]

MoAI-ADK が扱うワークツリーは大きく 2 層です。どちらも最終的には git worktree (1 つの git リポジトリが複数の作業ディレクトリを束ねる根本の仕組み) の上に乗っていますが、誰が作り、どこに置かれ、どれくらい長く生きるかが異なります。この違いを知っておかないと「いま自分はどの worktree で作業しているのか?」を勘違いしやすくなります。

1. L1 — .claude/worktrees/: プロジェクトディレクトリの内側に作られます。Claude Code ランタイムが自ら生成し、セッションが終わるときれいな状態のツリーは自動的に整理されます。セッション単位の一時空間と考えてください。
2. L2 — ~/.moai/worktrees/: プロジェクトの外、ユーザーのホームディレクトリの下に作られます。MoAI が SPEC 単位の並列開発のためにユーザーがオプトインして作り、run と sync の各段階を通じて同じツリーを再利用します。破棄はユーザーが moai worktree done で明示的に行う必要があります。

下の短い図で、2 層の場所と主体をひと目で把握します。より深い生成・破棄のライフサイクルと isolation: worktree の挙動は プラットフォーム基礎のワークツリードキュメント が扱います。

flowchart TD
    Repo[1 つの git リポジトリ
.git オブジェクトデータベースを共有]
    Repo --> L1[L1 — .claude/worktrees/
プロジェクト内、セッション単位の一時]
    Repo --> L2[L2 — ~/.moai/worktrees/
プロジェクト外、SPEC 単位の持続]
    L1 --> Who1[Claude Code ランタイムが自律生成]
    L2 --> Who2[MoAI がユーザーオプトインで生成]

鍵は 共有と隔離の分離です。リポジトリの履歴とリモート (remote) は 1 箇所で一緒に管理しつつ、作業ディレクトリとそこに紐づく LLM 設定だけをツリーごとに完全に切り離します。そのため、どの worktree でコミットしても他の worktree がただちにそのコミットを認識し、ブランチが絡まりません。MoAI-ADK はその上に「どの worktree に入るか」と「どの LLM モードで回すか」を一度に束ねるランチャー (moai cc · moai glm · moai cg) を載せたものです。

Worktree を使う MoAI-ADK 開発は 3 つの段階で流れます:

flowchart TD
    subgraph Phase1["Phase 1: Plan (Terminal 1, メインチェックアウト)"]
        A1["moai plan
機能の説明"] --> A2[SPEC ドキュメント生成]
        A2 --> A3[実装範囲の確定]
    end

    subgraph Phase2["Phase 2: Implement (Terminals 2, 3, 4...)"]
        B1["moai glm -w SPEC-AUTH-001"] --> B2[Worktree 生成および進入]
        B2 --> B3["moai run SPEC-ID"]
        B3 --> B4["moai sync SPEC-ID"]
    end

    subgraph Phase3["Phase 3: Merge & Cleanup"]
        C1[git merge または PR で
base へマージ] --> C2[moai worktree done ブランチ]
        C2 --> C3[Worktree 削除]
        C3 --> C4[任意: ブランチ削除]
    end

    Phase1 --> Phase2
    Phase2 --> Phase3

計画ステップは推論品質が結果を左右するので、Claude (Opus 級) モデルで SPEC ドキュメントを 書きます。このステップはメインチェックアウトでそのまま進めます:

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

成果物:

• .moai/specs/SPEC-AUTH-001/spec.md
• 実装ステップで使う SPEC ID

実装ステップは物量こそ多いものの、SPEC がすでに方向を定めているので、GLM のような安価な モデルでも十分に役割を果たします。ワークツリーへの進入はランチャー (moai cc · moai glm · moai cg) の -w フラグが担います。指定した名前のワークツリーがなければ、その場で作って くれます:

# 新しいターミナル: ワークツリーを作りながら GLM バックエンドで進入
$ moai glm -w SPEC-AUTH-001

# 進入したセッションからそのまま開発を開始
> /moai run SPEC-AUTH-001
> /moai sync SPEC-AUTH-001

現在のセッションを保ったままワークツリーをもう 1 つ開きたいときは --spawn を付けます。 tmux の新しいウィンドウで起動し、元のウィンドウはそのまま残ります:

$ moai glm -w SPEC-AUTH-002 --spawn

利点:

• 完全に隔離された作業環境
• GLM のコスト効率 (削減幅は CG モード を参照)
• 衝突のない無制限の並列開発

moai worktree done feature/SPEC-AUTH-001                    # worktree 整理 (マージ/プッシュは git で別途実行)
moai worktree done feature/SPEC-AUTH-001 --delete-branch    # 整理 + ローカルブランチ削除

ワークツリーへ入ることと一覧を見ることは moai worktree の役目ではありません。 進入はランチャーが、一覧表示は git が担います:

moai worktree は、作られたワークツリーを管理します:

SPEC ごとに Git 状態が別々に管理されます:

graph TD
    subgraph Main["Main Repository (main)"]
        M1[.moai/specs/]
        M2[リモートリポジトリと同期]
    end

    subgraph WT1["Worktree 1 (SPEC-AUTH-001)"]
        W1A[feature/SPEC-AUTH-001]
        W1B[独立した作業ディレクトリ]
        W1C[別の .moai/ 設定]
    end

    subgraph WT2["Worktree 2 (SPEC-AUTH-002)"]
        W2A[feature/SPEC-AUTH-002]
        W2B[独立した作業ディレクトリ]
        W2C[別の .moai/ 設定]
    end

    Main -.-> WT1
    Main -.-> WT2

利点:

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

Worktree ごとに LLM 実行モードを個別に決められます。下記のように 3 つのターミナルがそれぞれ moai cc (Claude 専用)、moai glm (GLM 専用)、moai cg (Claude リーダー + GLM ワーカーの ハイブリッド) で違う回り方をしても、互いに干渉しません:

sequenceDiagram
    participant T1 as Terminal 1
Worktree 1
    participant T2 as Terminal 2
Worktree 2
    participant T3 as Terminal 3
Worktree 3
    participant Main as Main Repository

    T1->>T1: moai cc (Claude)
    Note over T1: 高推論モデルで
計画を実行

    T2->>T2: moai glm
    Note over T2: 低コストモデルで
実装を実行

    T3->>T3: moai cg
    Note over T3: ハイブリッドで
品質・コストのバランス

    par 並列作業
        T1->>Main: Plan 作業
        T2->>Main: Implement 作業
        T3->>Main: Implement 作業
    end

    Main-->>T1: 完了した SPEC のみマージ
    Main-->>T2: 完了した SPEC のみマージ
    Main-->>T3: 完了した SPEC のみマージ

複数の SPEC を同時に進められます:

# Terminal 1: SPEC-AUTH-001 の計画 (メインチェックアウト)
> /moai plan "認証システム"

# Terminal 2: SPEC-AUTH-002 の実装 (GLM)
$ moai glm -w SPEC-AUTH-002
> /moai run SPEC-AUTH-002

# Terminal 3: SPEC-AUTH-003 の実装 (GLM)
$ moai glm -w SPEC-AUTH-003
> /moai run SPEC-AUTH-003

# Terminal 4: SPEC-AUTH-004 のドキュメント化 (Claude)
$ moai cc -w SPEC-AUTH-004
> /moai sync SPEC-AUTH-004

完了した SPEC だけが main ブランチへマージされます:

flowchart TD
    subgraph Development["開発中の Worktrees"]
        D1[SPEC-AUTH-001
進行中]
        D2[SPEC-AUTH-002
進行中]
        D3[SPEC-AUTH-003
完了]
    end

    subgraph Main["Main Repository"]
        M[main ブランチ]
    end

    D3 -->|git merge/PR の後に done で整理| M
    D1 -.->|まだ未完了| M
    D2 -.->|まだ未完了| M

複数のターミナルで同時に作業する様子です。worktree が完全に隔離されているおかげで衝突なく 並列に進みます。これがエージェンティック・ハーネスの核心です。ステップごとに適切なモデルを 割り当てられるのは、そこについてくるトークノミクスの利点です:

graph TD
    subgraph Terminal1["Terminal 1: Planning"]
        T1A["moai plan"]
        T1B[Claude Opus
高コスト/高品質]
        T1C[SPEC ドキュメント生成]
    end

    subgraph Terminal2["Terminal 2: Implementing"]
        T2A["moai glm -w
SPEC-AUTH-001"]
        T2B[低コストバックエンド]
        T2C["moai run
DDD 実装"]
    end

    subgraph Terminal3["Terminal 3: Implementing"]
        T3A["moai glm -w
SPEC-AUTH-002"]
        T3B[低コストバックエンド]
        T3C["moai run
DDD 実装"]
    end

    subgraph Terminal4["Terminal 4: Documenting"]
        T4A["moai cc -w
SPEC-AUTH-003"]
        T4B[Claude バックエンド]
        T4C["moai sync
ドキュメント化"]
    end

    T1C --> T2A
    T1C --> T3A
    T1C --> T4A

• 完全ガイド — すべての Worktree コマンドと詳しい使い方
• 実際の使用例 — 実際のプロジェクトへ適用した事例
• よくある質問 — FAQ および問題解決

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