並列実行とワークスペース

デフォルトの分離ブランチモードでは、実行中のタスクがそれぞれワークスペースを 1 つ占有します。そのため、複数のタスクを同時に実行するには、その数だけワークスペースが必要です。プライマリリポジトリを 1 つと数え、残りは自分で準備するレプリカでまかないます。レプリカは、git worktree または git clone を使って自分で作成し、依存関係をインストールしてから、cdg init を実行して登録します。CodeDAG が代わりにレプリカを作ることはなく、追加されたレプリカを自動で見つけることもありません。コンパイルもテストの実行もしないタスクには、代わりに共有ワークスペースモードを使えます。このモードにレプリカは必要ありません。

worktree と clone のどちらを選ぶか

レプリカは git worktree でも git clone でも作成できますが、1 つのプロジェクトで使えるのはどちらか一方だけです。ほとんどのプロジェクトでは、worktree のほうが手間がかかりません。worktree はプライマリリポジトリの Git データを共有するため、タスクブランチはどのワークスペースからもそのまま見えます。

clone は、worktree が向かないプロジェクトのためのものです。たとえば submodule を含むプロジェクトについては、Git のドキュメントが、複数の worktree をチェックアウトすることを推奨していません。clone を使う場合は、次の 2 点が worktree と異なります。

• タスクブランチは、そのタスクを実行した clone にだけ残る。 clone はそれぞれ独自のブランチを持ち、タスクの結果は CodeDAG が clone の間で受け渡します。ただし、ある clone で実行されたタスクのタスクブランチは、プライマリリポジトリからは見えません。
• ワークスペースに codedag-mirror という名前のリモートが追加される。 ワークフローの実行が始まると、プライマリリポジトリと各 clone にこのリモートが現れます。指しているのは、CodeDAG が手元のコンピューターで管理している同期リポジトリです。clone の間でブランチを受け渡すためのもので、自分のリモートリポジトリとは関係ありません。そのままにしておいてください。URL を変更すると、タスクが on-hold で止まります。対処方法は同期リポジトリが利用できないを参照してください。

レプリカを準備する

レプリカは、あらかじめ Git で作成し、clone したばかりのプロジェクトと同じように、依存関係のインストールとローカル設定のコピーを済ませておきます。そうして初めて、タスクをその中で正常に実行できます。いくつ準備するかは、ワークフローの中で同時に開始できるタスクの最大数に合わせて決めます。プライマリリポジトリも 1 つに数えるので、3 つのタスクを同時に実行したい場合は、レプリカをあと 2 つ準備します。プライマリリポジトリを自分用に残しておく場合（ワークフローの実行中に自分でも開発を続けるを参照）は、3 つ準備します。同時に実行するタスクが多いほど、エージェントの利用量も速く消費されます。同時実行と利用上限を参照してください。

以下では worktree を例に、プライマリリポジトリの隣にレプリカを 2 つ準備します。この 2 つのステップは、普段使っている Claude Code や Codex に任せることもできます。レプリカがいくつ必要か、どこに置くか、依存関係をどうインストールするか、どのファイルをコピーするかを伝えるだけです。

git worktree add ../my-app-wt-1 -b wt-1
git worktree add ../my-app-wt-2 -b wt-2

CodeDAG に登録する

レプリカの準備ができたら、プライマリリポジトリのルートで cdg init を実行し、このプロジェクトのワークスペースとして登録します。CodeDAG は、レプリカの追加や削除を自動では検出しません。そのため、レプリカを増やしたり減らしたりするたびに、もう一度実行する必要があります。

対話形式で登録する場合は、そのまま実行します。

cdg init

最初の質問 Select your repository setup method への答えで、レプリカの種類が決まります。

• worktree を使う場合は、1. I have set up git worktrees for this project を選びます。続いて、プライマリリポジトリ以外の worktree が一覧表示されるので、登録するものにチェックを付けます。パスを入力する必要はありません。Claude Code や Codex が自身のセッション用に作った worktree には、デフォルトではチェックが付いておらず、それ以外にはデフォルトでチェックが付いています。チェックを付けた worktree はタスクの実行に使われ、ブランチも切り替えられます。CodeDAG に任せたくないものは、スペースキーでチェックを外してください。登録する worktree を選ぶを参照してください。
• clone を使う場合は、2. I have cloned this repository into multiple directories を選びます。まずプライマリリポジトリのパスを確認し、続いて各 clone のパスをスペースで区切って入力します。

完了すると、出力の冒頭の Associated Replica Repositories の下に、登録されたレプリカが一覧表示されます。

非対話形式では、引数でパスを直接指定します。書き方は worktree でも clone でも同じで、パスはすべて絶対パスで書きます。

cdg init --primary-workdir /Users/you/my-app --replica-workdirs /Users/you/my-app-wt-1 /Users/you/my-app-wt-2

実行するたびに、登録済みのレプリカは、そのとき指定したリストにまるごと置き換えられます。そのため、引き続き使うレプリカはすべて書いておきます。そのほかのオプションは、「プロジェクトを初期化する」のオプションを参照してください。

タスクが実際に同時に実行されるには、同時実行数の上限 maxConcurrency もワークスペースの数に合わせておく必要があります。初めて初期化するとき、cdg init はこの値として、レプリカの数に 1 を加えた数を書き込みます。クイックスタートを済ませたあとなど、プロジェクトがすでに初期化されていて、元のローカル設定を残した場合は、cdg init が、その設定にある同時実行数の上限がワークスペースの数より小さいことを検出して、Update maxConcurrency to 3? と尋ねます。デフォルトは Yes なので、そのまま Enter を押します。非対話形式では尋ねられず、警告が出力されるだけです。コマンドに --max-concurrency 3 を付ければ、その値が直接書き込まれます。再初期化のときに既存のファイルがどう扱われるかは、再初期化と既存の設定の保持を参照してください。

レプリカを取り除くときは、まず git worktree remove で削除し、それから cdg init をもう一度実行して登録を更新します。削除済みのディレクトリが登録に残っていても、それだけでワークフローが止まることはありません。検証では、そのワークフローが使うはずのディレクトリのうち、存在しないもの 1 つにつき警告が 1 件出ます。警告には、このワークフローが残りのワークスペースで実行されることが書かれ、再初期化するよう案内されます。投入時には、警告を確認して先へ進めば問題ありません。検証がエラーになるのは、そのワークフローが使うワークスペースのディレクトリがすべて存在しない場合だけです。投入済みのワークフローがこの状況になると on-hold で止まるので、cdg init をもう一度実行してから、cdg dag recover で復旧します。

同時に実行されるタスクの数は何で決まるか

同時に実行されるタスクの数には、2 つの制限があります。同時実行数の上限 maxConcurrency と、利用できるワークスペースの数で、実際にはこのうち小さいほうが適用されます。そのため、同時実行数の上限を 4 にしていても、ワークスペースが 2 つしかなければ、同時に実行されるタスクは最大 2 つです。

同時実行数の上限は、次の順に決まります。先のものに値があれば、それより後ろは参照されません。

プロジェクト設定は投入時に読み込まれます。設定を変更しても、反映されるのはそのあとに投入したワークフローだけです。

利用できるワークスペースとは、登録済みのプライマリリポジトリとレプリカから、ワークフローが excludeWorkspaces で除外したものを除いたものです。分離ブランチモードのワークフローに maxConcurrency: 0 と書くと、上限を別に設けないという意味になり、利用できるワークスペースの数だけタスクが同時に実行されます。あとでレプリカを増減しても、この値を書き換える必要はありません。共有ワークスペースモードは例外です。すべてのタスクが同じワークスペースで実行されるため、同時に実行されるタスクの数は maxConcurrency だけで決まり、0 と書くと、開始できるタスクがすべて一斉に始まります。maxConcurrency を参照してください。

例として、プライマリリポジトリと worktree 2 つを登録した、ワークスペースが合計 3 つのプロジェクトを考えます。ワークフロー four-notes には互いに依存しないタスクが 4 つあり、maxConcurrency: 4 と書かれています。これらのタスクは互いにつながっていないため、検証では disconnected-dag の警告が 1 件出て、依存関係の書き漏れがないか確認するよう促されます。書き漏れがないことを確かめたら、投入時の Submit anyway? に Yes と答えます。投入後、cdg dag status four-notes は次のように表示します。

[TZ: -04:00] 2026-09-30 11:24:31

Workflow: .codedag/dags/four-notes.yaml
  Phase: 📤 submitted
  Queue Position: 1
  Status: 🟢 in-progress
  Substatus: working

Submitted Tasks (4):
  🟢 [in-progress] [working]  Task 1: Write note one
  🟢 [in-progress] [working]  Task 2: Write note two
  🟢 [in-progress] [working]  Task 3: Write note three
  🔘 [pending]     [blocked]  Task 4: Write note four

Progress: 0/4 tasks completed (0%)

最初の 3 つのタスクは、それぞれワークスペースを 1 つずつ使って同時に実行されています。タスク 4 には依存関係が 1 つもありませんが、[pending] [blocked] と表示されています。ワークスペースが空くのを待っているためです。タスク 1 が完了して自動承認されると、プライマリリポジトリが空き、タスク 4 がすぐにそこで開始されます。

ワークスペースは、タスクの開始からレビューの終了まで占有されます。done で止まってレビューを待っているタスクも、一時停止されたタスク、強制停止されたタスク、on-hold で止まっているタスクも、自分のワークスペースを占有したままです。これらのタスクが終わるまで、後続のタスクは待つしかありません。手動レビューを設定したノードが多いワークフローほど、早めにレビューするか、レプリカを 1 つ多く準備しておく必要があります。

ワークフローの実行中に自分でも開発を続ける

ワークフローファイルのトップレベルに excludeWorkspaces: ["."] と書くと、プライマリリポジトリが除外され、タスクはレプリカだけで実行されます。そのため、プロジェクトにはレプリカを 1 つ以上登録しておく必要があります。プライマリリポジトリのブランチは切り替えられず、そこに未コミットの変更を残していても、ワークフローの妨げになりません。結果を待つ間も、プライマリリポジトリでいつもどおり開発を続けられます。

excludeWorkspaces: ["."]   # プライマリリポジトリを使わず、タスクはレプリカだけで実行する
baseRef: main              # ワークフローの実行開始時に main が指しているコミットから始める
# tasks はいつもどおり書く

プライマリリポジトリを除外するときは、baseRef も一緒に書いておくことをおすすめします。baseRef を書かない場合、ベースは、ワークフローの開始時点で最初のレプリカにチェックアウトされているコミットになります。タスクを実行したことのあるレプリカは、いずれかのタスクブランチか統合ブランチをチェックアウトしたままになっているため、ベースはそこになり、想定していた main にはなりません。

baseRef が解決されるのは、ワークフローの実行が始まるときです。baseRef: main と書いた場合、ベースはその時点で main が指しているコミットになり、プライマリリポジトリでどのブランチに切り替えているかは関係ありません。キューで待っている間に main にコミットした変更も含まれます。特定のバージョンに固定したい場合は、タグかコミット ID を書きます。書き方は baseRef を参照してください。clone を使う場合、baseRef は最初の clone で解決され、main はその clone 自身の main を指します。あらかじめその clone で、main を目的のコミットまで更新しておいてください。

ワークフローが終了すると、統合ブランチは最初のレプリカに作られ、そのレプリカでチェックアウトされます。worktree を使っている場合、このブランチはプライマリリポジトリからも見えるので、プライマリリポジトリで git merge cdg/<ワークフロー名>/integration を実行すれば、そのままマージできます。clone を使っている場合、このブランチはその clone の中にあるので、そこから取得する必要があります。確認とマージの方法は、統合ブランチの結果を確認するとメインブランチにマージするを参照してください。

逆に、レプリカを 1 つ自分用に残し、プライマリリポジトリは通常どおりタスクの実行に使わせることもできます。その場合は、そのレプリカのパスを excludeWorkspaces に書きます。相対パスはプライマリリポジトリのルートを基準にし、たとえば excludeWorkspaces: ["../my-app-wt-2"] のように書きます。書き方は excludeWorkspaces を参照してください。

レプリカのディレクトリでコマンドを実行する

登録済みのワークスペースであれば、どこで cdg を実行しても、操作の対象は同じプロジェクトです。ワークフロー名はプライマリリポジトリの .codedag/dags/ を基準に解決され、投入先は同じキューで、表示される状態も同じです。タスクがどのワークスペースで実行され、どのコミットから始まるかは、ワークフローの設定だけで決まり、コマンドをどのディレクトリで実行したかには左右されません。レプリカから投入すると、Warning: You submitted this workflow from a registered replica/worktree. で始まるメッセージが追加で表示されます。これは、まさにこの点を知らせるためのものです。

レプリカには .codedag/ ディレクトリがないため、ワークフローファイルは、プライマリリポジトリの .codedag/dags/ で編集します。まだ登録していないレプリカは、どのプロジェクトにも属していません。その中でコマンドを実行すると、Cannot find initialized CodeDAG project. と表示されます。CodeDAG に登録するの手順に従い、プライマリリポジトリに戻って cdg init をもう一度実行してください。

cdg init の対象も、同じプロジェクトです。登録済みのレプリカで実行しても、初期化されるのはそのレプリカが属するプロジェクトであり、レプリカの中に .codedag/ が新しく作られることはありません。どのディレクトリで実行するかを参照してください。

よくある質問

同時実行数がずっと 1 のまま

特に多い原因は 3 つあります。1 つ目は、プライマリリポジトリしか登録していないことです。2 つ目は、レプリカを追加して再初期化したときに、同時実行数の上限を更新するかどうかの質問に No と答えたため、ローカル設定の maxConcurrency が 1 のままになっていることです。3 つ目は、タスク同士に依存関係があり、もともと同時には実行できないことです。最初の 2 つは、CodeDAG に登録するの手順で対処します。原因を調べる順序の全体は、同時実行数が 1 にしかならないを参照してください。

プライマリリポジトリのブランチが切り替わっている

分離ブランチモードでは、これは想定どおりの動作です。プライマリリポジトリもワークスペースの 1 つなので、実行中はタスクブランチに切り替えられ、ワークフローの終了後は統合ブランチをチェックアウトした状態になります。メインブランチそのものは変更されていません。ワークフローの終了後、リポジトリはどのブランチにあるかを参照してください。プライマリリポジトリを実行に使わせたくない場合は、ワークフローの実行中に自分でも開発を続けるの方法で除外します。

レプリカのタスクではテストが失敗するのに、プライマリリポジトリでは通る

多くの場合、レプリカに依存関係かローカルの設定ファイルが足りていません。レプリカを準備するのステップ 2 に従って、各レプリカに依存関係をインストールし、設定をコピーして、git status がクリーンであることを確認してください。タスクがまだ実行中であれば、インストールが済んだあとに cdg task view でセッションに入り、テストを実行し直させることができます。セッションに入る、修正する、抜けるを参照してください。タスクがすでに完了し、レビュー待ちで止まっている場合は、今の結果をもとに修正を続けさせることができます。

並列に実行したタスクのブランチは、自分で下流にマージする必要がありますか

必要ありません。分離ブランチモードでは、下流のタスクが始まる前に、そのタスクが依存する上流の承認済みの結果を、CodeDAG が自動でそのタスクブランチにマージします。コンフリクトも、まずエージェントが解決します。そのため、ワークフローにマージ用のタスクを別に追加する必要はありません。合流ノードでのマージとコンフリクトを参照してください。

関連ページ

• ワークスペースとブランチ：ワークスペースがなぜ並列実行の前提になるのか、タスクブランチと統合ブランチがどのように構成されるのか。
• 2 つ目のワークフロー：コードを変更させる：プライマリリポジトリと worktree 1 つを使って、2 つのタスクを並列に実行する一連の流れ。
• プロジェクトを初期化する：cdg init のすべてのオプションと、再初期化のルール。