ワークフローファイルを書く

ワークフローファイルは、プライマリリポジトリの .codedag/dags/ ディレクトリに置く YAML または JSON のファイルで、実行するタスクとタスク間の依存関係を記述します。必須なのは、各タスクの id、title、prompt だけです。タスクをどのエージェントが実行するか、実行中に許可を待つかどうか、完了後にレビューを待つかどうかは、それぞれ省略可能なフィールドで指定し、書かなければデフォルト値が使われます。

手で書きたくない場合

CodeDAG Guide プラグインを入れた Claude Code や Codex にやりたいことを伝えれば、ワークフローファイルの作成、検証、投入、進捗の追跡までを任せられます。方法はエージェントにオーケストレーションを任せるを参照してください。エージェントが書いたファイルは手で書いたものと変わらず、同じく .codedag/dags/ に置かれます。このページの以降の各セクションは、そうしたファイルを読んで確認するときにも役立ちます。

ファイルの置き場所

ワークフローファイルは、プライマリリポジトリ（.codedag/ があるリポジトリ）の .codedag/dags/ ディレクトリに置きます。CodeDAG がワークフローを読み込むのは、このディレクトリからだけです。ファイル名から拡張子を除いたものがワークフローの名前になり、コマンドではこの名前で指定します。たとえば .codedag/dags/testing-docs.yaml は、cdg dag validate testing-docs で検証できます。この名前はタスクブランチ名やログファイル名にも使われるため、短い英小文字の名前にしておくと扱いやすくなります。

ファイル形式は YAML（.yaml、.yml）と JSON（.json）のどちらでもかまいません。使えるフィールドはまったく同じです。複数行のプロンプトを自然に書け、コメントも付けられるので、YAML をおすすめします。cdg init が .codedag/dags/ に生成する untitled_dag.yaml は、コメント付きの空のテンプレートです。コピーして名前を変えれば、そこから書き始められます。

.codedag/ は、プロジェクトリポジトリから独立したサイドカーリポジトリです。そのため、新しく作ったワークフローファイルは、プロジェクトリポジトリの git status には表示されません。ワークフローファイルの変更履歴を残したい場合は、ワークフローと共有設定を別に保存するを参照してください。

最小構成

ワークフローファイルには、少なくとも tasks のリストが必要です。リストにはタスクを 1 つ以上書き、各タスクには id、title、prompt を必ず書きます。タスクの前後関係は dependencies で表します。次のワークフローには、タスクが 2 つあります。タスク 1 はプロジェクトのテストコマンドをまとめてファイルに書き、タスク 2 はそのファイルを読んで、README にテストの説明を追加します。

tasks:                                # タスクのリスト。タスクが 1 つ以上必要
  - id: 1                             # タスク番号。ワークフロー内で一意の正の整数
    title: テストコマンドをまとめる   # 人が読むための短いタイトル。ステータスボードに表示される
    prompt: |                         # タスクエージェントへの指示。| は、以降が複数行のテキストであることを表す
      リポジトリにあるビルドとテストの設定（package.json、Makefile、CI の設定など）を読み、
      すべてのテストをローカルで実行するコマンドと、そのために必要な準備の手順を調べて、
      docs/notes/testing.md に書いてください。
      書くのはこのファイルだけです（すでにある場合はそのまま上書きします）。ほかのファイルは変更しないでください。

  - id: 2
    title: READMEにテストの説明を追加
    dependencies: [1]                 # タスク 1 が完了して承認されてから開始する
    prompt: |
      docs/notes/testing.md を読み、README.md に「テストの実行」という節を追加して、
      ローカルでテストを実行する方法を 3〜5 ステップで説明してください。変更するのは README.md だけにしてください。

タスク 2 のプロンプトには、読むファイルのパスを明記しています。どのタスクも新しいエージェントセッションで、上流タスクの会話は見えず、上流がリポジトリに残したファイルしか読めないからです。タスクの分け方とプロンプトの書き方は、タスクの分割とプロンプトの書き方を参照してください。

プロンプトが 1 行だけであれば、コロンの後ろにそのまま書けます。ただし、内容に半角コロンとスペースの組み合わせ（Goal: ... など）が含まれていると、YAML がそれをキーと値のペアと解釈して、構文エラーになります。その場合も、| を使った複数行の書き方にしてください。

このファイルはすでに検証に通りますが、どのエージェントが実行するかも、権限モードも指定していません。このまま投入すると、2 つのタスクはどちらもプロジェクトのデフォルトのエージェントが実行し、そのエージェント自身の権限設定がそのまま使われます。その設定がファイルの変更やコマンドの実行に許可を求めるものであれば、タスクは止まって人の応答を待ちます。実際に投入するときは、通常、各タスクに agent と mode も書きます。書き方はよく使うフィールドを参照してください。

よく使うフィールド

実行の制御でよくある要望には、それぞれ対応するフィールドがあります。「タスク」と記したフィールドは tasks の各項目の中に書き、そのタスクだけに影響します。「ワークフロー」と記したフィールドは、ファイルのトップレベルに tasks と並べて書き、ワークフロー全体に適用されます。

「省略した場合」の列は、ほかに何も設定していないときの結果です。このうちいくつかの項目は、プロジェクト設定や cdg dag submit のオプションでも設定できます。同じ項目を複数の場所で設定した場合は、投入コマンドのオプションがファイルのフィールドより優先され、タスクのフィールドがワークフローのフィールドより優先され、ファイルのフィールドがプロジェクト設定より優先されます。優先順位の全体は、デフォルト値と優先順位を参照してください。

次の例は、最小構成の例にフィールドを書き足し、実際に投入する形にしたものです。使用するエージェントに合わせて、どちらかのバージョンを選んでください。

tasks:
  - id: 1
    title: テストコマンドをまとめる
    agent: claude             # Claude Code が実行する
    mode: bypassPermissions   # フルアクセス。実行中に許可待ちで止まらない
    model: sonnet             # 情報をまとめる作業なので、速いモデルを使う
    autoAccepted: none        # 完了したら止まり、結果の確認を待ってから先へ進む
    prompt: |
      リポジトリにあるビルドとテストの設定（package.json、Makefile、CI の設定など）を読み、
      すべてのテストをローカルで実行するコマンドと、そのために必要な準備の手順を調べて、
      docs/notes/testing.md に書いてください。
      書くのはこのファイルだけです（すでにある場合はそのまま上書きします）。ほかのファイルは変更しないでください。

  - id: 2
    title: READMEにテストの説明を追加
    dependencies: [1]
    agent: claude
    mode: bypassPermissions
    model: opus               # 読者に向けた文章なので、より高性能なモデルを使う
    prompt: |
      docs/notes/testing.md を読み、README.md に「テストの実行」という節を追加して、
      ローカルでテストを実行する方法を 3〜5 ステップで説明してください。変更するのは README.md だけにしてください。

tasks:
  - id: 1
    title: テストコマンドをまとめる
    agent: codex              # Codex が実行する
    mode: yolo                # フルアクセス。実行中に許可待ちで止まらない
    effort: medium            # 情報をまとめる作業なので、中程度の推論エフォートを使う
    autoAccepted: none        # 完了したら止まり、結果の確認を待ってから先へ進む
    prompt: |
      リポジトリにあるビルドとテストの設定（package.json、Makefile、CI の設定など）を読み、
      すべてのテストをローカルで実行するコマンドと、そのために必要な準備の手順を調べて、
      docs/notes/testing.md に書いてください。
      書くのはこのファイルだけです（すでにある場合はそのまま上書きします）。ほかのファイルは変更しないでください。

  - id: 2
    title: READMEにテストの説明を追加
    dependencies: [1]
    agent: codex
    mode: yolo
    effort: high              # 読者に向けた文章なので、より高い推論エフォートを使う
    prompt: |
      docs/notes/testing.md を読み、README.md に「テストの実行」という節を追加して、
      ローカルでテストを実行する方法を 3〜5 ステップで説明してください。変更するのは README.md だけにしてください。

タスク 1 が完了すると、ワークフローは止まってレビューを待ちます。タスク 1 がまとめた内容を確認してから cdg task review accept 1 -w testing-docs を実行して結果を承認すると、タスク 2 が開始されます。

検証する

cdg dag validate は、ワークフローファイルの形式、フィールドの値、依存関係をローカルでチェックします。ログインは不要で、クレジットも消費しないため、書いている途中で何度でも実行できます。ワークフロー名を複数並べれば、まとめて検証できます。

cdg dag validate testing-docs

結果は、成功、警告付きの成功、失敗の 3 種類です。失敗した場合は、エラーが 1 件ずつ出力されます。たとえば、タスク 2 が存在しないタスク 3 に依存している場合は、次のようになります。

✗ Validation failed: .codedag/dags/testing-docs.yaml
  [dag] Task 2: depends on non-existent task 3

検証で読み込まれるのは、このファイルだけではありません。2 つのプロジェクト設定ファイルも一緒に読み込まれ、設定項目の値が不正な場合は、検証はその時点で失敗し、どのファイルのどの項目かが示されます。フィールドの値のうち、mode は、タスクが実際に使うエージェントの書き方に合っているかどうかがチェックされます。一方、model や effort のようにエージェントにそのまま渡される値は、チェックの対象外です。各フィールドで何がチェックされるかは、ワークフローファイルリファレンスを参照してください。

警告があっても検証は失敗しませんが、1 件ずつ確認しておくことをおすすめします。最もよくあるのは unsupported-field です。CodeDAG は、ワークフローファイルにある未知のフィールドを無視します。そのため、フィールド名のつづりを間違えてもエラーにはならず、そのフィールドが効かないだけです。フィールド名はすべて camelCase で書きます。auto_accepted のように snake_case で書いた場合も同じく無視され、あわせて naming の警告が、autoAccepted に直すよう促します。

投入時には、cdg dag submit がもう一度検証を実行し、エラーがあれば投入されません。検証や投入に失敗したときの調べ方は、投入が拒否されたを参照してください。

関連ページ

• タスクの分割とプロンプトの書き方：タスクを分割して依存関係を組み、新しいセッションでも単独でやり遂げられるプロンプトを書く方法。
• 投入、監視、ログ：検証に通ったワークフローを投入し、実行の進捗とログを確認します。
• ワークフローファイルリファレンス：各フィールドの型、すべての値、デフォルト値、優先順位。