エージェントにオーケストレーションを任せる

この方法とは

CodeDAG Guide プラグインを入れた Claude Code や Codex は、cdg の使い方を知っています。何を実現したいかを自然言語で伝えれば、タスクの分割、ワークフローファイルの作成、検証、投入までを行い、実行中は進捗を追跡して、終了後に結果を報告します。このように、ユーザーに代わって cdg を操作するエージェントをオーケストレーションエージェントと呼びます。一方、ワークフロー内の各タスクはこれまでどおり新しいセッションが実行し、そのセッションをタスクエージェントと呼びます。役割分担について詳しくは、誰が何を担当するかを参照してください。

自分で書く場合と違うのは、誰がファイルを書き、誰がコマンドを実行するかだけです。ワークフローファイルは同じくプライマリリポジトリの .codedag/dags/ に置かれ、フィールドも、コマンドも、状態も、自分で書く場合と変わりません。エージェントが投入する前にファイルを開いて確認や修正ができますし、いつでも自分で cdg コマンドを実行して、状況を確認したり介入したりできます。ただし、投入済みのワークフローは投入時点の定義で実行されるため、後からファイルを変更しても、その実行には影響しません。

前提条件

この方法を使うには、CodeDAG が使える状態になっていること、Claude Code または Codex に CodeDAG Guide プラグインが入っていること、そしてプラグインのインストール後に開いたセッションを使っていることが必要です。

• インストールとログインを済ませていること。
• Claude Code のフルアクセスの警告に同意済みであること。このコンピューターで Claude Code のタスクをフルアクセスで実行したことが一度もない場合は、先に同意を済ませておきます。ターミナルで claude --permission-mode bypassPermissions を実行し、「Yes, I accept」を選んで終了してください。以降は尋ねられません。忘れていても、後から対応できます。その場合、タスクは保留になり、同意されるのを待ちます。対処方法は、Claude Code のフルアクセスの警告にあらかじめ同意するを参照してください。
• プラグインがインストール済みであること。このリポジトリで cdg init を実行したときにプラグインのインストールを選んだか、User スコープでインストールしたことがあれば（どのリポジトリでインストールしたかは問いません）、この条件は満たされています。そうでない場合は、cdg plugin install --scope user を実行します。このコンピューターにインストールされている Claude Code と Codex にプラグインが入り、自分のすべてのリポジトリで有効になります。
• プラグインのインストール後に開いたセッションであること。プラグインは新しいセッションでしか有効になりません。すでに開いているセッションは、いったん終了してから claude --resume または codex resume で再開してください。

判断がつかないときは、このリポジトリで cdg plugin status を実行して確認します。該当するエージェントの下の Plugin installed と Enabled がどちらも true であれば、プラグインはインストール済みで、有効になっています。未インストールと表示された場合は、出力の Action の行に、インストール用のコマンドが示されます。インストールスコープと更新方法は、CodeDAG Guide プラグインを管理するを参照してください。

そのまま貼り付けて使えるプロンプト

作業対象のリポジトリのルートで Claude Code または Codex の新しいセッションを開き、次のプロンプトを貼り付けます。依頼する内容は 2 つ目のワークフローのチュートリアルと同じで、まず TODO を 2 つ見つけ、それを 2 つのタスクで 1 つずつ実装します。

CodeDAG を使って、次の作業を進めてください。まずワークフローファイルを書いて私に見せ、私が確認してから投入してください。

目標：このプロジェクトの中から、最も早く片付けられる TODO を 2 つ見つけ、それぞれ実装してください。どちらも、まず最小限のテストを書き、そのテストが通るまで実装します。TODO は、私の役割と担当範囲に合わせて絞り込んでください。コード中の TODO や FIXME コメント、ドキュメント内の TODO リスト、スキップされているテストのほか、GitHub Issues、Linear、Jira など、アクセスできる issue トラッカーから選んでもかまいません。適切な TODO が見つからない場合は、このプロジェクトの製品としての位置づけと現状、および私の職務を踏まえて、代わりに小さな変更を 2 つ提案してください。

タスクの分割：お任せします。私の想定は次のとおりです。まず 1 つのタスクでこの 2 つの TODO を選び、それぞれの目標、対象ファイル、完了条件を docs/plans/agent-todos.md に書きます。次に、2 つのタスクで 1 つずつ、同時に実装します。

アクセスレベル：すべてのタスクをフルアクセスにして、無人実行で最後まで走らせてください。それでも実行中に許可を求めるタスクがあった場合は、まずその内容を私に知らせてください。私の代わりに許可しないでください。

レビュー：TODO を選ぶタスクが完了したら止めて、私が計画を確認してから続けてください。それ以外のタスクは、完了したら自動承認されるようにしてください。

ワークスペース：プロジェクトに登録済みのワークスペースは、どれを使ってもかまいません。プライマリリポジトリしかない場合は、タスクを順番に実行してください。ベースは、プライマリリポジトリの現在のコミットにします。投入する前に、これらのワークスペースに未コミットの変更がないことを確認してください。変更があった場合は私に知らせてください。私の代わりにコミットしたり破棄したりしないでください。

報告：すべて終了したら、各タスクが何をしたか、結果がどのブランチにあるか、テストが通ったかどうか、私が注意すべき点を教えてください。メインブランチへのマージは、私が自分で行います。

プロンプトの冒頭では、CodeDAG を使うことを明示し、投入前にワークフローを見せるよう求めています。CodeDAG を使うという指定は省けません。これがないと、エージェントはワークフローを書かずに、現在のセッションでそのままコードを変更し始める可能性が高いからです。続く 6 つの項目には、それぞれ役割があります。「目標」は、検証できる結果として書きます。「タスクの分割」はすべてエージェントに任せてもかまいませんが、自分の想定を伝えておくと、やり取りの回数を減らせます。「報告」には、終了時に知りたいことを書きます。「アクセスレベル」「レビュー」「ワークスペース」の 3 つは今回の実行の範囲を定めるもので、エージェントが投入前に知っておく必要があります。それぞれの意味は、投入前にエージェントと確認しておく 3 つのことを参照してください。自分の目標に置き換えるときは、この構成を残して、内容だけを書き換えてください。

投入前にエージェントと確認しておく 3 つのこと

アクセスレベル、ワークスペース、手動レビューは、それぞれ今回の実行で何ができるか、どこで作業するか、どこで止まるかを決めます。初めて使うときに自分で決める必要があるのはアクセスレベルだけで、残りの 2 つは、何も伝えなければデフォルトのとおりに実行されます。

• アクセスレベル。 フルアクセスでは、タスクエージェントは操作の前に同意を求めないため、ワークフローを無人実行で最後まで走らせられます。中程度のアクセスでは、許可が必要な操作に当たるとタスクが止まり、ユーザーが応答するか、あらかじめ取り決めた範囲内でオーケストレーションエージェントが代わりに応答するのを待ちます。どちらのレベルを使うかを伝えていない場合、オーケストレーションエージェントは投入前にユーザーに尋ねます。2 つのレベルのトレードオフは、無人実行か有人実行かを決めるを参照してください。
• ワークスペース。 デフォルトでは、プライマリリポジトリを含め、プロジェクトに登録済みのワークスペースがすべて実行に使われ、ワークフローはプライマリリポジトリの現在のコミットから始まります。実行中にプライマリリポジトリで別の開発作業もしたい場合は、プライマリリポジトリを CodeDAG のワークスペースから外すよう、エージェントに伝えます。詳しくはワークフローの実行中に自分でも開発を続けるを参照してください。
• 手動レビュー。 デフォルトでは、各タスクは完了すると自動承認され、ワークフローが途中で止まることはありません。あるタスクの結果を確認してから先へ進めたい場合は、プロンプトでそのタスクを名指しします。詳しくはレビューゲートと自動承認を参照してください。

エージェントが行うこと

プロンプトを受け取ってから結果を報告するまで、オーケストレーションエージェントは、CodeDAG Guide が定めるデフォルトの手順に沿って進めます。ユーザーから別の指示がある場合は、その指示が優先されます。

1. 準備状況を確認する。 まず、プロジェクトが初期化済みかどうかと、どのワークスペースを使えるかを確認します。プロジェクトがまだ初期化されていなければ、ユーザーに代わって cdg init を実行します。
2. ワークフローを書き、確認を求める。 目標をタスクに分割して、.codedag/dags/ にワークフローファイルとして書き、求められていれば、まずユーザーに見せます。ユーザーがファイルを直接開いて確かめることもできます。読み方は、ワークフローファイルを書くを参照してください。
3. 検証して投入する。 まず cdg dag validate を実行し、エラーがあれば修正し、警告があれば先に原因を突き止めます。そのうえで cdg dag submit を実行します。先に確認したいと伝えてある場合は、ユーザーの確認を待ってから投入します。
4. 実行を追跡する。 投入後の最初の数分間は、ステータスとログを頻繁に確認し、すべてのタスクが正常に開始されたことを確かめます。安定してからは、確認の頻度を 5〜10 分に 1 回まで落とします。こまめに確認してもタスクが速くなるわけではなく、オーケストレーションエージェント自身のセッションのコンテキストを消費するだけだからです。あるタスクで新しい出力が長時間なくても、止まったままになっているとは限りません。タスクエージェントがサブエージェントを起動し、バックグラウンドで作業させている可能性があります。そのため通常は、まったく動きのない状態が 10 分以上続いてから、介入して様子を確認します。
5. 実行中の操作の許可リクエストに応答する。 許可の対象は、タスクの実行途中の個々の操作です。コマンドの実行など、設定されたアクセスレベルでは通らない操作をタスクエージェントが行おうとすると、タスクは止まって人の許可を待ちます。このときオーケストレーションエージェントは、tmux の中で cdg task view を実行してそのタスクのセッションに入り、画面に表示されている許可リクエストの内容を読み取ります。取り決めた範囲内であれば、ユーザーに代わって応答し、セッションから抜けて、タスクに実行を続けさせます。範囲を超えていれば、内容をユーザーに伝えて判断を待ちます。オーケストレーションエージェントがコマンドを実行する環境には、通常、対話型ターミナルがありません。そのため、この手順には、このコンピューターに tmux がインストールされている必要があります。tmux がない場合、許可リクエストには、ユーザー自身がセッションに入って応答するしかありません。方法は許可リクエストに応答するを参照してください。
6. 完了後の結果レビューを進める。 レビューの対象は、タスクが終わった後の結果全体です。結果は、承認されて初めて下流のタスクに渡されます。タスクが完了後にレビュー待ちで止まった場合（手動レビューを設定していた場合や、タスクが変更を何も残さなかったために止められた場合）、オーケストレーションエージェントはまずそのタスクのログと変更を確認し、取り決めに沿って進めます。結果を承認するか、タスクエージェントに今の結果をもとに修正を続けさせるか、判断をユーザーに委ねるかのいずれかです。
7. 結果を報告する。 ワークフローが終了すると、各タスクが何をしたか、変更がどのブランチにあるかを報告します。デフォルトの分離ブランチモードでは、すべてのタスクの結果が統合ブランチ cdg/<ワークフロー名>/integration にマージされており、タスクごとのタスクブランチもあります。メインブランチは変更されません。オーケストレーションエージェントが共有ワークスペースモードを選んだ場合は、これらのブランチはなく、結果は作業ディレクトリにそのまま残ります。

追跡が行われるのは、このセッションを開いている間だけです。セッションを閉じてもワークフローには影響せず、バックグラウンドでそのまま実行が続きますが、代わりに見ていてくれるエージェントはいなくなります。進捗は、いつでも自分で cdg status を実行して確認できます。新しいセッションを開いて、追跡を引き継がせることもできます。

実行が長時間に及ぶと、タスクエージェントが Claude Code や Codex 自体の利用上限（たとえば 5 時間のウィンドウ）に達することがあります。その場合、タスクは途中で止まり、オーケストレーションエージェントはまず、影響を受けるほかのタスクを止めます。上限がリセットされたら、止まっていたタスクを元のセッションで再開させます。この再開で CodeDAG クレジットがさらに消費されることはありません。対処の手順全体は、エージェントの利用上限またはレート制限を参照してください。

エージェントが代わりに行わないこと

オーケストレーションエージェントが肩代わりするのは、ファイルを書くこと、コマンドを打つこと、進捗を見張ることです。安全上の境界と最終的な結論を決めるのは、引き続きユーザーです。

• 安全上の境界は決めない。 どのアクセスレベルを使うか、タスク内の許可リクエストに誰が応答するかは、ユーザーが決めます。オーケストレーションエージェントは、決められた方針に従うだけです。
• 取り決めの範囲外では許可しない。 取り決めた範囲を超える許可リクエストや、削除や上書きのような破壊的な操作については、いずれも先にユーザーに尋ねます。
• メインブランチへのマージも、リモートへのプッシュもしない。 結果はローカルのリポジトリに残るだけです。CodeDAG 自体も、リモートリポジトリへのプッシュやリモートリポジトリからのプルを行いません。確認とマージの方法は、仕上げ、マージ、クリーンアップを参照してください。明示的に依頼すれば、これらの Git コマンドを代わりに実行させることもできます。
• 目標が達成されたかどうかは判断しない。 ワークフローの終了が意味するのは、すべてのタスクの実行が終わり、ルールに従って承認されたということだけです。しかも、デフォルトの自動承認は、結果が正しいかどうかを確認しません。オーケストレーションエージェントは、各タスクが何をしたか、どこに注意が必要かを報告します。コードをマージできるかどうかは、ユーザーが確認したうえで決めます。

これらの境界は、CodeDAG Guide の指針と、ユーザーとエージェントとの間の取り決めによるもので、プログラムが強制する制限ではありません。オーケストレーションエージェントが自らコマンドを実行するときに従うのは、そのセッション自体の権限設定だけです。リモートへのプッシュなど、特定の操作を必ずユーザーの同意を得てから実行させたい場合は、この権限設定で担保する必要があります。

次のステップ

• CodeDAG Guide プラグインを管理する：インストールスコープの選択、プラグインの更新、そしてプラグイン付属のスキルファイルを変更せずにオーケストレーションの動作をカスタマイズする方法。
• エージェント、モデル、権限モードを選ぶ：タスクごとのアクセスレベルを決める前に、フルアクセスと中程度のアクセスがそれぞれ何と引き換えになるのかを確認します。