ワークフローファイルリファレンス

ワークフローファイルは、プライマリリポジトリの .codedag/dags/ ディレクトリに置く YAML または JSON のファイルです。必須なのは、tasks のリストと、各タスクの id、title、prompt だけです。それ以外のフィールドはすべて省略でき、省略した場合は、プロジェクト設定の値か、フィールドごとのデフォルト値が使われます。ワークフローファイルを一から書く手順は、ワークフローファイルを書くを参照してください。

やりたいことからフィールドを探す

フィールドには 2 つのレベルがあります。「ワークフロー」と記したフィールドは、ファイルのトップレベルに tasks と並べて書き、ワークフロー全体に適用されます。「タスク」と記したフィールドは、tasks の項目の中に書き、そのタスクだけに影響します。

ファイルの置き場所と形式

ワークフローファイルは、プライマリリポジトリの .codedag/dags/ ディレクトリか、その下の任意の階層のサブディレクトリに置きます。拡張子は .yaml、.yml、.json のいずれかです。それ以外の場所に置いたファイルや、それ以外の拡張子のファイルは、検証も投入もできません。コマンドでワークフローファイルを指定する方法は、ワークフローを指定するを参照してください。

ワークフローの名前は、.codedag/dags/ からのファイルの相対パスで決まります。相対パスから拡張子を除き、含まれている / をアンダースコアに置き換えたものが名前です。.codedag/dags/build.yaml の名前は build、.codedag/dags/team/build.yaml の名前は team_build になります。この名前はタスクブランチと統合ブランチの名前に使われ、このページでは <ワークフロー名> と書きます。したがって、2 つ目の例の統合ブランチは cdg/team_build/integration です。Git のブランチ名に使えない文字がほかに含まれている場合は、その文字もあわせて正規化されます。実際の名前がはっきりしないときは、cdg dag status が出力する Integration Branch で確認してください。

別々のサブディレクトリにある同名のファイルは、ワークフローとしては別の名前になります。ログファイルも同じ相対パスで保存されるため、互いに影響しません。一方、build.yaml と build.yml のように拡張子だけが異なる 2 つのファイルは同じ名前になり、同じブランチ名と同じログファイルを共有します。

YAML と JSON で使えるフィールドはまったく同じです。ファイルは、さらに次の制限も満たす必要があります。

• フィールド名： 大文字と小文字が区別され、すべて camelCase で書きます。CodeDAG が認識しないフィールドがあっても検証は失敗せず、そのフィールドは無視されて警告が出ます。検証するを参照してください。
• YAML の構文： アンカー（&）、エイリアス（*）、マージキー（<<）はサポートされておらず、ファイルで使うと検証に失敗します。繰り返し使う内容は、その都度そのまま書いてください。文字列の内容に含まれる & と * の文字は、この制限を受けません。
• ネストの深さ： 64 階層を超えることはできません。通常の構造で書いたワークフローファイルが、この制限に近づくことはまずありません。
• ファイルサイズとタスク数： ワークフローファイル 1 つのサイズは 256 KiB までです。サイズは、ファイルの内容そのものの UTF-8 バイト数で数え、コメントと空白も含みます。1 つのワークフローに含められるタスクは、最大 1024 個です。この 2 つは、投入時にサーバー側でチェックされ、cdg dag validate ではチェックされません。上限を超えている場合、cdg dag submit は拒否されます。

ワークフローレベルのフィールド

ワークフローレベルのフィールドは、ファイルのトップレベルに書きます。tasks 以外はすべて省略できます。maxConcurrency、taskAutoAccepted、dagAutoAccepted を省略した場合は、まずプロジェクト設定にある同名のフィールドの値が使われます。優先順位の全体は、デフォルト値と優先順位を参照してください。

tasks

tasks はタスクのリストで、ワークフローファイルで唯一の必須フィールドです。値は配列で、タスクを 1 つ以上含める必要があります。各タスクには、少なくとも id、title、prompt を書きます。使えるフィールドの一覧は、タスクレベルのフィールドを参照してください。

tasks:
  - id: 1
    title: テストコマンドをまとめる
    prompt: すべてのテストをローカルで実行するコマンドを調べて、docs/notes/testing.md に書いてください。

executionMode

executionMode は、タスクをそれぞれのブランチで分離して実行するか、同じワークスペースでそのまま実行するかを決めます。省略可能なフィールドで、値は isolated-branches または shared-workspace です。省略した場合は isolated-branches になります。

2 つのモードがある理由と、それぞれの代償は、実行モードを参照してください。どちらのモードを選ぶかによって、ほかのいくつかのフィールドとレビューのオプションの動作も変わります。

executionMode: shared-workspace   # タスクはプライマリリポジトリの現在のブランチでそのまま実行される

maxConcurrency

maxConcurrency は、同時に実行するタスク数の上限で、省略可能な整数です。正の整数を書くと、最大でその数のタスクが同時に実行されます。0 または負の数を書くと、ワークフロー自体には上限を設けないという意味になります。省略した場合は、プロジェクト設定の maxConcurrency が使われます。cdg init がデフォルトで書き込む値は、レプリカの数に 1 を足した数です。プロジェクト設定にもない場合は 1 になり、タスクは 1 つずつ実行されます。

分離ブランチモードでは、実行中のタスクがそれぞれワークスペースを 1 つ占有します。そのため、実際の同時実行数が、利用できるワークスペースの数を超えることもありません。利用できるワークスペースとは、登録済みのワークスペースのうち、excludeWorkspaces で除外していないものです。0 または負の数にした場合、同時実行数は、利用できるワークスペースの数と同じになります。利用できるワークスペースが足りない場合は、先にレプリカを増やします。レプリカを準備するを参照してください。

共有ワークスペースモードでは、同時実行数はワークスペースの数による制限を受けません。0 または負の数にした場合は、開始できるタスクがすべて同時に始まります。これらのタスクは同じワークスペースに書き込み、CodeDAG はその変更を分離しません。そのため、同時に実行されるタスクには、それぞれ別のファイルに書き込ませる必要があります。

maxConcurrency: 2   # 最大 2 つのタスクを同時に実行する

maxConcurrency: 0   # ワークフローには上限を設けない。分離ブランチモードでは、利用できるワークスペースをすべて使う

taskAutoAccepted

taskAutoAccepted は、ワークフロー内のすべてのタスクに適用されるデフォルトのレビューポリシーです。タスクの完了後に自動承認するか、止まってレビューを待つかを決めます。省略可能なフィールドで、値は always、done、none のいずれかです。それぞれの意味は、自動承認に指定できる値を参照してください。省略した場合は、プロジェクト設定の taskAutoAccepted が使われます。プロジェクト設定にもない場合は always、つまり自動承認になります。

タスク自身に autoAccepted が書かれている場合は、タスクの値が優先されます。さらに、投入時に --task-auto-accepted オプションを付けると、その投入に限って、この両方を上書きできます。デフォルト値と優先順位を参照してください。

taskAutoAccepted: none   # すべてのタスクが完了後に止まり、レビューを待つ
tasks:
  - id: 1
    title: コードをフォーマット
    autoAccepted: always # このタスクは例外で、完了後に自動承認される
    prompt: プロジェクトのフォーマットコマンドを実行し、すべてのソースファイルをフォーマットしてください。

dagAutoAccepted

dagAutoAccepted は、ワークフロー全体のレビューポリシーです。すべてのタスクのレビューが終わったあとに、ワークフロー全体を自動承認するか、止まって結果全体についての結論を待つかを決めます。タスクのレビューポリシーとは独立しており、すべてのタスクが自動承認された場合でも、ワークフロー全体が止まるかどうかは、このフィールドで決まります。省略可能なフィールドで、値は always、done、none のいずれかです。それぞれの意味は、自動承認に指定できる値を参照してください。省略した場合は、プロジェクト設定の dagAutoAccepted が使われます。プロジェクト設定にもない場合は done、つまり自動承認になります。投入時に --dag-auto-accepted オプションを付けると、その投入に限って、このフィールドを上書きできます。

dagAutoAccepted: none   # すべてのタスクが終わったあと、ワークフロー全体についての結論を待つ

baseRef

baseRef は、ワークフローのベースを指定します。分離ブランチモードでは、すべてのタスクブランチがこのコミットから作られます。省略可能な、空でない文字列で、次のいずれの形式でも書けます。

書いた値は、ただ 1 つのコミットに対応していなければなりません。同じ名前のブランチとタグが両方ある場合や、短縮したコミット ID が複数のコミットに一致する場合、CodeDAG はどれを指しているかを推測しません。前者の場合は refs/heads/... や refs/tags/... のような完全な参照名に書き換え、後者の場合はコミット ID をより長く書いてください。

baseRef が特定のコミットに解決されるのは、投入コマンドの実行時ではなく、ワークフローの実行が実際に始まるときです。そのため、baseRef: main と書いた場合、ベースは、ワークフローが始まった時点で main が指しているコミットになり、キューで待っている間に main に追加されたコミットも含まれます。検証でチェックされるのは、空文字列でないことだけです。参照が存在するかどうか、ただ 1 つに決まるかどうかは、ワークフローが始まるまで確定しません。解決に失敗した場合、ワークフローは on-hold で止まります。対処方法は、ワークフローが実行を開始できないを参照してください。

baseRef を省略した場合、ベースは、ワークフローの実行開始時の、プライマリリポジトリの HEAD です。プライマリリポジトリが excludeWorkspaces で除外されている場合は、除外されていない最初のレプリカの HEAD です。前のワークフローが終了すると、プライマリリポジトリは、そのワークフローの統合ブランチをチェックアウトしたままになります。そのため、baseRef を書いていない次のワークフローは、前のワークフローの結果の続きから始まります。ワークフローの終了後、リポジトリはどのブランチにあるかを参照してください。どんな場合でも main から始めたいときは、baseRef: main と書きます。

共有ワークスペースモードでは、baseRef は解決されて記録されるだけで、CodeDAG がそれに合わせてワークスペースを切り替えることはありません。共有ワークスペースモードのタスクを特定のバージョンで実行したい場合は、先に自分でそのワークスペースを目的のコミットに切り替えてから、ワークフローを投入します。

baseRef: main     # ワークフローの開始時に main が指しているコミットから始める

baseRef: v1.4.0   # タグ v1.4.0 から始める

excludeWorkspaces

excludeWorkspaces には、このワークフローで使わないワークスペースを列挙します。省略可能な文字列の配列で、各項目はワークスペースのパスです。. はプライマリリポジトリを表します。相対パスはプライマリリポジトリのルートを基準とし、絶対パスで書くこともできます。どの項目も、現在のプロジェクトに登録済みのワークスペースでなければならず、そうでない場合は検証に失敗します。ワークスペースの登録は、ワークスペースの登録と更新を参照してください。省略した場合は、登録済みのワークスペースをすべて使えます。

分離ブランチモードでは、除外されたワークスペースでは、ブランチが切り替えられることも、タスクが実行されることもありません。その分だけ利用できるワークスペースが減り、実際の同時実行数も下がることがあります。共有ワークスペースモードでは、ワークフローは、除外されていない最初のワークスペースで実行されます。順序は、プライマリリポジトリが先頭で、そのあとにレプリカが登録順に並びます。どちらのモードでも、ワークスペースを少なくとも 1 つ残す必要があります。登録済みのワークスペースをすべて除外すると検証に失敗し、ワークフローは投入されません。

プライマリリポジトリを除外すると、ワークフローはレプリカだけで実行され、プライマリリポジトリでは開発を続けられます。その場合は、baseRef も一緒に書いておくことをおすすめします。書かないと、ベースは、最初のレプリカにその時点でチェックアウトされているコミットになります。方法は、ワークフローの実行中に自分でも開発を続けるを参照してください。

excludeWorkspaces: ["."]   # プライマリリポジトリを使わず、ワークフローはレプリカだけで実行する
baseRef: main

excludeWorkspaces:
  - ../my-app-wt-2         # このレプリカを使わない（別の作業で使用中の場合など）

mergeConflictAgent

mergeConflictAgent は、自動マージでコンフリクトが起きたときに、どのエージェントが解決するかを指定します。省略可能なオブジェクトで、分離ブランチモードでだけ有効です。分離ブランチモードでは、CodeDAG は 2 つの場面で自動マージを行います。下流のタスクが始まる前に、上流の結果をそのタスクブランチにマージするときと、すべてのタスクが終わったあとに、結果を統合ブランチにマージするときです。どちらの場面でコンフリクトが起きても、CodeDAG は解決のためのエージェントセッションを起動します。解決できなかった場合は、対応するタスクまたはワークフローが on-hold で止まります。仕組みは合流ノードでのマージとコンフリクト、対処の手順はマージコンフリクトを参照してください。

mergeConflictAgent を省略した場合は、2 つの場面のそれぞれに、別々のデフォルトがあります。

mergeConflictAgent を書いた場合は、どちらの場面でも、そのオブジェクトに書いた agent、mode、model が使われます。model を省略しても、下流タスクの model が引き継がれることはありません。

コンフリクト解決のセッションには、許可リクエストに応答する手段がありません。そのため、このセッションはタスクの mode を引き継ぎません。mergeConflictAgent に mode を書いていない場合は、フィールド全体を省略した場合も含めて、常に yolo で動作し、無人実行でもマージを終えられます。mode を書くのは、別のアクセスレベルに変えたい場合だけです。止まって許可を求めるレベルに変えると、セッションは許可リクエストが出た時点で止まり、マージを先へ進められなくなります。

mergeConflictAgent:        # すべてのマージコンフリクトの解決を Claude Code に任せる
  agent: claude
  model: opus

metadata

metadata は、ワークフローの用途、メンテナー、バージョンなど、人が読むための説明を記録するフィールドです。省略可能なオブジェクトで、内容は自由に決められます。CodeDAG がその内容を読み取ることも、チェックすることもありません。cdg init が生成するテンプレートファイルには、version や description などの項目がいくつか入っています。必要に応じて、そのまま残しても、変更しても、削除してもかまいません。

metadata:
  description: 週次の依存関係アップグレードと回帰テスト
  owner: platform-team

タスクレベルのフィールド

タスクレベルのフィールドは、tasks の各項目の中に書き、そのタスクにだけ適用されます。

id

id は、タスクの番号です。dependencies と、cdg task 配下のコマンドは、この番号でタスクを指定します。必須の正の整数で、同じワークフロー内で重複してはいけません。ただし、1 から始める必要も、連番にする必要もありません。

title

title は、タスクの名前です。ステータスボードとログに表示され、デフォルトのタスクブランチ名の生成にも使われます。必須の文字列で、空にはできません。タスクエージェントが受け取るのは prompt だけで、title は見えません。エージェントに伝える必要がある内容は、prompt に書いてください。

prompt

prompt は、タスクエージェントへの指示です。タスクのエージェントセッションは、これを最初の入力として受け取ります。必須の文字列で、互換用の書き方である details を代わりに使うこともできます。少なくとも、どちらか一方を書く必要があります。一方だけを書く場合は、どちらを書いても動作は同じです。両方を書いた場合は prompt だけが使われ、details の内容は使われません。prompt を書く場合は、空にはできません。空文字列でも、空白だけの文字列でも、検証に失敗します。

どのタスクも新しいエージェントセッションで、ほかのタスクの会話は見えません。そうしたセッションが単独でやり遂げられるプロンプトの書き方は、プロンプトを書く：新しいセッションが単独でやり遂げられるようにするを参照してください。

  - id: 2
    title: 検索APIを実装
    prompt: |
      docs/plans/search.md を読み、まず計画にある新しい API のそれぞれにユニットテストを書いてから、
      計画に沿って検索 API を実装し、すべてのテストが通るまで実行してください。
      変更するのは server/ ディレクトリだけにしてください。

description

description は、人が読むための補足説明です。省略可能な文字列で、デフォルトは空です。タスクエージェントには渡されないため、エージェントに伝えたい内容は prompt に書いてください。

dependencies

dependencies には、このタスクが待つ上流タスクの id を列挙します。省略可能な整数の配列で、デフォルトは空の配列です。空の配列の場合、タスクはどのタスクも待たず、ワークフローが始まればすぐに実行の対象になります。列挙する id は、どれも同じワークフローに存在するタスクのものでなければなりません。依存関係が循環していてもいけません。タスクが自分自身に依存している場合も、循環とみなされます。

タスクは、すべての上流が完了し、レビューを通ってから開始されます。自動承認も、レビューを通ったものとして扱われます。分離ブランチモードでは、タスクが始まる前に、上流の結果がそのタスクブランチにマージされます。

  - id: 4
    title: テストを実行して修正
    dependencies: [2, 3]   # タスク 2 とタスク 3 がどちらもレビューを通ってから開始する
    prompt: すべてのテストを実行し、すべて通るまで失敗を修正してください。

agent

agent は、このタスクを実行するエージェントを指定します。claude は Claude Code、codex は Codex を表します。省略可能なフィールドで、省略した場合は、プロジェクトのデフォルトのエージェントが使われます。これはプロジェクト設定の defaultAgent のことで、通常は cdg init のときに決まります。指定するエージェントは、プロジェクトで使えるエージェントに含まれていなければならず、そうでない場合は検証に失敗します。

タスクの mode の書き方は、そのタスクが実際に使うエージェントに合わせてチェックされます。agent を省略した場合、mode はプロジェクトのデフォルトのエージェントに合わせてチェックされます。デフォルトのエージェントは通常ローカル設定に記録されているため、同じファイルでも、デフォルトのエージェントが異なるマシンに持っていくと、検証に失敗することがあります。そのため、mode を書いたタスクには、agent も明記しておくことをおすすめします。

  - id: 3
    title: 実装をレビュー
    agent: claude             # このタスクだけを Claude Code に任せる
    mode: bypassPermissions
    prompt: server/ ディレクトリに今回追加されたコードをレビューし、見つかった問題を docs/review.md に書いてください。

mode

mode は、タスクエージェントの権限モードです。タスクの実行中に、どの操作をそのまま実行でき、どの操作でいったん止まって許可を待つかを決めます。省略可能な、空でない文字列です。省略した場合、CodeDAG はエージェントに権限モードを渡さず、エージェントは自身の設定に従って動作します。たとえば、Claude Code のプロジェクト設定またはユーザー設定にある permissions.defaultMode や、Codex の ~/.codex/config.toml です。この場合、タスクの実際のアクセスレベルは、ワークフローファイルからは読み取れません。

mode の書き方は、エージェントによって異なります。権限モードの構文を参照してください。タスクを無人実行で最後まで進めたい場合や、各タスクのアクセスレベルをファイルで固定したい場合は、mode を明記します。無人実行と有人実行のどちらを選ぶかは、無人実行か有人実行かを決めるを参照してください。

  - id: 1
    title: 実装計画を書く
    agent: codex
    mode: yolo                # Codex：許可を求めず、サンドボックスも使わない
    prompt: docs/spec/search.md を読み、実装計画を docs/plans/search.md に書いてください。
  - id: 2
    title: 検索APIを実装
    dependencies: [1]
    agent: claude
    mode: acceptEdits         # Claude Code：ファイルの編集はそのまま実行し、それ以外のコマンドは事前に許可を求める
    prompt: docs/plans/search.md に沿って検索 API を実装してください。

model

model は、タスクが使うモデルを指定します。省略可能な、空でない文字列で、エージェントの --model オプションにそのまま渡されます。省略した場合は、エージェント側で設定されているデフォルトのモデルが使われます。CodeDAG はモデル名をチェックしません。名前を書き間違えても検証には通り、タスクの実行時になって初めて、エージェントがエラーを出します。

Claude Code では、sonnet、opus、haiku のようなエイリアスを書けるほか、完全なモデル名も書けます。Claude Code のモデル設定のドキュメントを参照してください。Codex では、モデル名を書きます。使えるモデルは、Codex のモデルのドキュメントを参照してください。

  - id: 3
    title: 実装をレビュー
    agent: claude
    model: sonnet   # 最新の Sonnet モデルを使う
    prompt: server/ ディレクトリに今回追加されたコードをレビューし、見つかった問題を docs/review.md に書いてください。

effort

effort は、モデルの推論エフォートを指定します。省略可能な、空でない文字列で、エージェントにそのまま渡されます。省略した場合は、エージェント自身の設定か、使用するモデルのデフォルト値で決まります。CodeDAG は値をチェックしません。値を書き間違えても、タスクの実行時になるまで問題は表面化しません。

どちらのエージェントでも、使えるレベルは選んだモデルによって決まり、上位のいくつかのレベルを使えないモデルもあります。詳しくは、Claude Code のモデル設定のドキュメントと、Codex のモデルのドキュメントを参照してください。

  - id: 1
    title: 実装計画を書く
    agent: codex
    effort: high    # 計画は後続のすべてのタスクを左右するので、高めの推論エフォートを使う
    prompt: docs/spec/search.md を読み、実装計画を docs/plans/search.md に書いてください。

autoAccepted

autoAccepted は、このタスクのレビューポリシーです。タスクの完了後に自動承認するか、止まってレビューを待つかを決めます。省略可能なフィールドで、値は always、done、none のいずれかです。それぞれの意味は、自動承認に指定できる値を参照してください。省略した場合は、ワークフローの taskAutoAccepted が引き継がれます。ワークフローにも書かれていない場合は、プロジェクト設定、最終的なデフォルト値の always の順に使われます。投入時に --task-auto-accepted オプションを付けると、その投入に限って、すべてのタスクのこのフィールドを上書きできます。デフォルト値と優先順位を参照してください。

  - id: 1
    title: 実装計画を書く
    autoAccepted: none   # 計画を書き終えたら止まる。承認して初めて、下流のタスクが開始される
    prompt: docs/spec/search.md を読み、実装計画を docs/plans/search.md に書いてください。

branchName

branchName は、このタスクのタスクブランチ名を指定します。省略可能な、空でない文字列です。使えるのは分離ブランチモードだけで、共有ワークスペースモードで書くと検証に失敗します。省略した場合、CodeDAG はタスクブランチに cdg/<ワークフロー名>/t<id>-<タイトル> という名前を自動で付けます。

branchName を書いた場合、CodeDAG はその名前をそのまま使い、プレフィックスもサフィックスも付けません。名前は次の条件を満たしている必要があり、満たしていない場合は検証に失敗します。

• Git のブランチ名の規則に従っていること。つまり、git check-ref-format を通ること。
• 同じワークフロー内のほかのタスクと重複していないこと。
• このワークフローの統合ブランチ cdg/<ワークフロー名>/integration と同じ名前ではなく、スナップショットブランチのプレフィックス cdg/<ワークフロー名>/snapshots/ で始まってもいないこと。

同じ名前のブランチがすでに存在する場合、検証は branch-name-conflict の警告を出します。たとえば、同じワークフローの前回の実行で残ったブランチがある場合です。対処せずに投入すると、ワークフローの実行がこのタスクまで進んだところで、タスクは on-hold で止まります。警告には、その名前を何が使っているかが示されます。古いブランチを片付ければ、元の名前を引き続き使えます。方法は、指定したタスクブランチ名を使うを参照してください。自動で命名されるタスクブランチでは、この問題は起きません。そのため、branchName を書くのは、ブランチ名を固定する必要が本当にある場合だけにしてください。たとえば、あとでそのブランチをリモートにプッシュして、プルリクエストを作成する場合です。

  - id: 2
    title: 検索APIを実装
    branchName: feature/search-api
    prompt: docs/plans/search.md に沿って検索 API を実装してください。

自動承認に指定できる値

always、done、none の 3 つの値は、レビューポリシーのすべての設定で使います。タスクの autoAccepted、ワークフローの taskAutoAccepted と dagAutoAccepted、プロジェクト設定にある同名のフィールド、そして cdg dag submit の --task-auto-accepted オプションと --dag-auto-accepted オプションです。名前に dag が含まれる設定はワークフロー全体に適用され、それ以外はタスクに適用されます。それぞれの値が、この 2 種類の設定で持つ意味は次のとおりです。

0.1.0 では、always と done の動作は同じで、どちらも自動承認を表します。最終的なデフォルト値は、タスクが always、ワークフローが done です。そのため、何も書かなければ、タスクもワークフローも自動承認されます。

自動承認には、例外が 1 つあります。分離ブランチモードでは、完了したタスクが変更を何も残していない場合、always に設定していても自動承認されず、止まってレビューを待ちます。共有ワークスペースモードでは、ゼロ出力のタスクも通常どおり自動承認され、ステータスにその旨が表示されるだけです。

none は、自分の目で確認したい箇所に使います。たとえば、後続のタスクがすべて依存する計画のタスクや、初めて実行する新しいワークフローです。どのノードにこの設定をする価値があるか、なぜ自動承認がデフォルトなのかは、自動承認を参照してください。止まったあとのレビューの方法は、タスクとワークフローをレビューするを参照してください。

権限モードの構文

mode は、タスクと mergeConflictAgent に書けます。書き方は、対応するエージェントによって決まります。Claude Code ではモード名を 1 つ書き、Codex では省略形を 1 つ書くか、カンマで区切ったキーと値のペアを書きます。検証では、対応するエージェントに合わせて形式がチェックされます。一方のエージェント向けの書き方を、もう一方のエージェントのタスクに使うと、検証に失敗します。

Claude Code

Claude Code のタスクの mode には、モード名を 1 つ書きます。モード名には、スペース、カンマ、= を含められません。CodeDAG は、それを --permission-mode オプションとして Claude Code に渡します。CodeDAG は、エイリアスを 2 つ用意しています。yolo は bypassPermissions と同じで、askForPermissions は default と同じです。それ以外のモード名は、そのまま Claude Code に渡されます。CodeDAG がチェックするのは形式だけで、名前が有効かどうかは Claude Code が判断します。

各モードの完全な説明は、Claude Code の権限モードのドキュメントで確認してください。

mode: acceptEdits   # ファイルの編集はそのまま実行し、それ以外のコマンドは実行前に許可を求める

Codex

Codex のタスクの mode は、2 通りの書き方のどちらかで書きます。mode 全体を 1 つの省略形にするか、カンマで区切った複数の キー=値 にするかです。2 つの書き方は混ぜられず、approve-for-me,search=true のような書き方は検証に失敗します。

2 つの省略形は、それぞれが権限設定一式を表します。

• yolo： Codex は、どの操作でも許可を求めず、サンドボックスも使わず、リアルタイムの Web 検索を有効にします。あらゆるファイルの読み書き、ネットワークへのアクセス、あらゆるコマンドの実行ができるため、信頼できるタスクと、自分で管理できる環境でだけ使ってください。Codex 自身のオプション名である dangerously-bypass-approvals-and-sandbox と書いても、同じ動作になります。
• approve-for-me（auto と書いてもかまいません）： Codex は workspace-write サンドボックスの中で動作し、サンドボックスの外に出る必要があるときは、その都度許可を求めます。ただし、許可リクエストはまず Codex の自動レビューが判断するため、人を待って止まることはありません。リクエストが拒否された場合、エージェントは自分でやり方を調整して作業を続けます。無人実行ができるうえ、レビューの段階も 1 つ残ります。

キーと値で書く場合は、次の 5 つのキーを使えます。各キーを書けるのは 1 回までで、カンマの前後にはスペースを入れてもかまいません。書かなかったキーは Codex に渡されず、Codex 自身の設定で決まります。

5 つのキーは、自由に組み合わせられます。追加の条件があるのは network_access だけで、これを書く場合は、sandbox=workspace-write も必ず明記します。表にないキー名、表にない値、重複したキーは、いずれも cdg dag validate と cdg dag submit の段階でエラーになり、そのまま Codex に渡されることはありません。表に挙げているのは、現在のバージョンの Codex が受け付ける値です。Codex の以前の許可ポリシーである untrusted と、Codex ですでに非推奨になった on-failure は、どちらも含まれていません。これらを書くと、ask-for-approval must be on-request or never, received 'untrusted' のようなエラーになります。

# タスクのワークスペースへの書き込みだけを許可し、その外に出るときはモデルが許可を求める
mode: "ask-for-approval=on-request,sandbox=workspace-write"

# 上の設定に加えて、コマンドのネットワークアクセスを許可する（依存関係のインストールやテスト用サービスへのアクセスなど）
mode: "ask-for-approval=on-request,sandbox=workspace-write,network_access=true"

# 許可リクエストを Codex の自動レビューに任せる。ユーザーの応答を待って止まることはない
mode: "approvals_reviewer=auto_review,ask-for-approval=on-request,sandbox=workspace-write,network_access=true"

# リアルタイムの Web 検索を有効にするが、コマンドのネットワークアクセスは許可しない
mode: "sandbox=workspace-write,search=true"

# 許可を一切求めない：サンドボックス内でできる操作はそのまま実行し、できない操作はその場で失敗する。タスクが人を待って止まることはない
mode: "ask-for-approval=never,sandbox=workspace-write,network_access=true"

許可とサンドボックスの詳しい動作は、Codex の設定のドキュメントで確認してください。

デフォルト値と優先順位

同じ設定項目は、複数の場所に書けます。cdg dag submit のオプション、タスクのフィールド、ワークフローのフィールド、プロジェクトのローカル設定 .codedag/local/settings.local.jsonc、共有設定 .codedag/settings.jsonc です。CodeDAG は投入時に、次の表の左から右の順に調べ、値が書かれている最初の設定元を使います。どこにも書かれていない場合は、最終的なデフォルト値を使います。

値は投入時に確定します。そのあとでファイルや設定を変更しても、すでに投入したその実行には影響しません。表の最後の行は例外です。タスクに mode、model、effort が書かれていない場合、CodeDAG は代わりに値を決めません。エージェントが、セッションを起動するたびに、その時点の自身の設定に従って決めます。そのため、投入後にエージェントの設定を変更すると、まだ起動していないタスクは新しい設定で動作します。その実行で特定の権限モードやモデルを固定して使いたい場合は、タスクに明記してください。

投入コマンドの 2 つのオプションは、その投入にだけ適用され、どのファイルも変更しません。使い方は、今回の投入に限ってレビュー設定を調整するを参照してください。ローカル設定と共有設定にそれぞれ何を書くか、自分にだけ適用するにはどうするかは、設定を書く場所を参照してください。自動マージでコンフリクトが起きたときにどのエージェントを使うかには、別のルールがあります。mergeConflictAgent を参照してください。

そのほかの設定例

次の 2 つのファイルは、どちらも完結したワークフローです。そのまま .codedag/dags/ に保存し、自分のプロジェクトに合わせてプロンプトを書き換えて使えます。

1 つ目のワークフローは、レプリカだけで実行され、常に main から始まります。そのため、同時にプライマリリポジトリで開発を続けられます。タスク 1 とタスク 2 は同時に実行され、それぞれレプリカを 1 つ占有するため、プロジェクトにはレプリカを 2 つ以上登録しておく必要があります。タスク 3 が始まる前に、CodeDAG は先の 2 つのタスクの結果を、タスク 3 のタスクブランチにマージします。

baseRef: main              # main から始める。プライマリリポジトリが今どのブランチにあるかには左右されない
excludeWorkspaces: ["."]   # プライマリリポジトリを使わず、ワークフローはレプリカだけで実行する
maxConcurrency: 2
tasks:
  - id: 1
    title: フロントエンドの依存関係をアップグレード
    agent: codex
    mode: yolo
    prompt: |
      web/ ディレクトリの依存関係を、現在のメジャーバージョン内の最新バージョンにアップグレードし、
      web/ のすべてのテストを実行して、失敗したテストを修正してください。変更するのは web/ ディレクトリだけにしてください。
  - id: 2
    title: バックエンドの依存関係をアップグレード
    agent: codex
    mode: yolo
    prompt: |
      server/ ディレクトリの依存関係を、現在のメジャーバージョン内の最新バージョンにアップグレードし、
      server/ のすべてのテストを実行して、失敗したテストを修正してください。変更するのは server/ ディレクトリだけにしてください。
  - id: 3
    title: アップグレード内容を記録
    dependencies: [1, 2]
    agent: codex
    mode: yolo
    prompt: |
      今回のアップグレード前後の依存関係のバージョンを比較し、どの依存関係をアップグレードしたか、注意が必要な変更は何かを
      docs/notes/deps-upgrade.md に書いてください。書くのはこのファイルだけです（すでにある場合はそのまま上書きします）。

2 つ目のワークフローは、まず計画を書き、書き終えたところで止まって確認を待ちます。そのあと、2 つのタスクが API とページをそれぞれ実装します。2 つの実装タスクには固定のブランチ名を使っているので、あとで個別にプッシュしやすくなります。すべてのタスクが終わったあと、統合ブランチへのマージでコンフリクトが起きた場合は、Claude Code に解決を任せます。

mergeConflictAgent:              # マージでコンフリクトが起きたら、Claude Code に解決を任せる
  agent: claude
tasks:
  - id: 1
    title: 実装計画を書く
    agent: codex
    mode: yolo
    autoAccepted: none           # 計画を書き終えたら止まり、確認を待ってから実装を始める
    prompt: |
      docs/spec/search.md を読み、検索機能の実装計画を docs/plans/search.md に書いてください。
      変更するモジュール、API の変更点、テストの要点を挙げてください。書くのは計画だけで、コードは変更しないでください。
  - id: 2
    title: 検索APIを実装
    dependencies: [1]
    agent: codex
    mode: yolo
    branchName: feature/search-api
    prompt: |
      docs/plans/search.md に沿って検索 API を実装し、対応するユニットテストを追加してください。
      すべてのテストが通るまで実行してください。
  - id: 3
    title: 検索ページを実装
    dependencies: [1]
    agent: claude
    mode: bypassPermissions
    branchName: feature/search-ui
    prompt: |
      docs/plans/search.md に沿って検索ページを実装し、対応するコンポーネントテストを追加してください。
      すべてのテストが通るまで実行してください。

関連ページ

• ワークフローファイルを書く：最小構成からワークフローファイルを書き始め、投入前に検証します。
• エージェント、モデル、権限モードを選ぶ：タスクごとに、エージェント、モデル、アクセスレベルを選びます。
• プロジェクト設定：共有設定とローカル設定のフィールドと、そのデフォルト値。
• 検証と投入：cdg dag validate と cdg dag submit の引数とオプション。