レビューゲートと自動承認

タスクが完了しても、その結果は、レビューを経て初めて下流に渡されます。すべてのタスクの結果が 1 つにまとまったあと、ワークフロー全体ももう一度レビューを受けます。どちらのレビューもデフォルトでは自動的に通りますが、このとき結果が正しいかどうかは確認されません。そのため、人が確認すべきノードは、あらかじめそこで止まって待つように設定しておく必要があり、投入したあとは変更できません。実行が止まったら、結果を承認することも、エージェントに修正を続けさせることも、最初からやり直させることも、その結果を採用しないこともできます。いったん出した結論は、その実行の中では変更できません。

レビューゲート

タスクエージェントが作業を終えたからといって、結果が使えるとは限りません。問題のある結果をそのまま下流に渡してしまうと、それを土台にした作業はすべてやり直しになります。そこで、結果は下流に渡す前にレビューを受け、認められたものだけが通されます。結果を認めるのは自分でもよく、あらかじめ決めたルールに従って自動で認めることもできます。実行の流れの中でこのレビューが行われる場所が、レビューゲート（review gate）です。

CodeDAG には 2 つのゲートがあります。タスクレベルのゲートは、各タスクが完了してから、そのタスクに依存する下流が始まるまでの間にあり、タスクの結果を下流に渡してよいかどうかを決めます。ワークフローレベルのゲートは、ワークフロー全体の最後にあります。個々のタスクの結果には問題がなくても、合わせたときにも問題がないとは限りません。そのため、すべてのタスクに結論が出て、結果が 1 つにまとまったあとで、結果全体についてもう一度判断します。この判断が済んで初めて、ワークフローは終了したことになります。

タスクが完了すると、ステータスが done になり、タスクレベルのゲートでレビューを受けます。レビューを通ると、タスクは reviewed フェーズに入り、ここで初めて、そのタスクに依存する下流が始まります。すべてのタスクが reviewed になると、デフォルトの分離ブランチモードでは、CodeDAG が各タスクの結果を統合ブランチにマージし、続いてワークフローがワークフローレベルのゲートでレビューを受けます。これを通ると、ワークフローは reviewed になってキューを離れ、後ろで待っていたワークフローの実行が始まります。2 つのゲートでのレビューには、それぞれ cdg task review と cdg dag review を使います。

どちらのゲートも、開いておくか閉じておくかを設定できます。開いていれば結果は自動的に通り、閉じていれば実行が止まって、結論が出されるのを待ちます。

%%{init: {"flowchart": {"rankSpacing": 34}}}%%flowchart TD  t1["タスクが完了：done"] --> g1{{"タスクレベルのゲート"}}  g1 -->|開いている：自動承認| r1["タスクが reviewed になる"]  g1 -->|閉じている| w1["止まってレビューを待つ"]  w1 -->|ユーザーが<br/>最終的な結論を出す| r1  r1 --> d1["依存する下流タスクが始まる"]  r1 -.->|すべてのタスクが<br/>reviewed になる| m1["結果を統合ブランチにマージ"]  m1 --> g2{{"ワークフローレベルのゲート"}}  g2 -->|開いている：自動承認| r2["ワークフローが reviewed になる<br/>キューを離れる"]  g2 -->|閉じている| w2["止まってレビューを待つ"]  w2 -->|ユーザーが<br/>最終的な結論を出す| r2

自動承認

すべての結果で人のレビューを待っていては、無人実行が有人実行に逆戻りしてしまいます。それに、ほとんどの結果は 1 つずつ目を通す必要のないものです。そこで、CodeDAG の 2 つのゲートは、どちらもデフォルトで開いています。結果は完了と同時に自動的に通り、これを自動承認（auto-accept）と呼びます。自分でレビューする価値のあるノードでだけゲートを閉じておけば、実行はそこで止まって待ちます。

ゲートを開くか閉じるかは、ワークフローファイルに書きます。タスクの autoAccepted はそのタスク 1 つに対する設定で、ワークフローの taskAutoAccepted はワークフロー内のすべてのタスクのデフォルト値、dagAutoAccepted はワークフローレベルのゲートに対する設定です。値が none のとき、対応するゲートは閉じています。指定できる値の一覧は、自動承認に指定できる値を参照してください。

ゲートを閉じる価値があるノード

閉じるゲートは、数を絞り、場所をよく選ぶ必要があります。ゲートを 1 つ閉じるたびに代償が生じるからです。タスクがゲートの前で止まっている間は、そのタスクに依存する下流も待たされます。分離ブランチモードでは、止まっているタスクが自分のワークスペースを占有し続けるため、同時に実行できるタスクも減ります。ワークフローレベルのゲートを閉じている場合は、キューの後ろで待っているワークフローも、結論が出るまで始まりません。ゲートを閉じる価値があるのは、通常、次のようなノードです。

• 後続のタスクすべての土台になるノード。 実装計画やインターフェース契約などです。ここに誤りがあると、下流の作業がすべて無駄になります。その直後でいったん止めるのが、最も代償の小さい方法です。
• 初めて実行する新しいワークフロー。 プロンプトが十分に明確かどうかまだ確信が持てないときは、taskAutoAccepted を none にして、タスクを 1 つずつ確認します。問題がないとわかってから、自動承認に戻します。
• 後ろにほかのワークフローが並んでいるワークフロー。 baseRef を書いていない場合、次のワークフローは、デフォルトではこのワークフローの結果の続きから始まります（ベースを参照）。ワークフローレベルのゲートを閉じておけば、次のワークフローが始まる前に、この結果を確認できます。

逆に、ワークフローを 1 つだけ実行する場合、ワークフローレベルのゲートは、通常はデフォルトのままで十分です。CodeDAG がメインブランチを変更することはなく、結果を最終的にメインブランチに入れるかどうかは、もともと自分で決めることだからです。

変更を残さなかったタスクは自動承認されない

分離ブランチモードでは、完了したタスクが変更を何も残していない場合、ゲートが開いていても自動承認されず、止まってレビューを待ちます。このモードでは、タスクの成果はすべてブランチ上の変更として現れます。何も変更せずに終わったタスクは、実際には作業をやり遂げられていないことが少なくありません。途中で中断された、結論をファイルに書かなかった、といった場合です。これを自動で通してしまうと、下流は必要な入力が欠けたまま始まることになります。本当にファイルを変更する必要のないタスクは、内容を確認したうえで、手動で承認すれば済みます。

共有ワークスペースモードでは、このチェックは結果を知らせるだけで、タスクを止めることはありません。詳しくは共有ワークスペースモードでは、レビューはどう変わりますかを参照してください。

レビューアクション

実行がゲートの前で止まっているときに使えるレビューアクションは、2 種類に分かれます。最終アクションは結論を出すもので、そのノードはそこで終わります。継続アクションは結論を出さず、タスクに修正を続けさせるもので、修正が終わると、タスクは再びゲートの前に戻ります。

最終アクションは 3 つあります。accept（承認）は結果を通します。cancel（キャンセル）は、その結果を採用しないことを表します。defer（見送り）は、このステップを今は採用せず、あとで対処することを表します。3 つとも、タスクを reviewed にします。キャンセルまたは見送りの場合、分離ブランチモードでは、そのタスク自身の変更は下流に渡されません。下流が実行を続けるか、止まって対処を待つか、一緒に終わるかは、レビューのときに選びます。自動承認は、CodeDAG がルールに従って、ユーザーの代わりに accept を実行したのと同じです。このときのレビュー結果は auto-accepted と記録され、自分で出した accepted と区別されます。

継続アクションも 3 つあり、誰が修正するか、どこから修正を始めるかが違います。revise（自分で修正）では、タスクのワークスペースで自分で修正し、修正が済んだら最終的な結論を出します。request-changes（修正依頼）では、フィードバックを元のセッションに渡し、今ある結果の続きから修正させます。rework（やり直し）では、現在の結果をスナップショットに保存するか破棄したうえで、タスク開始前のクリーンベースラインから新しいセッションを起動し、最初からやり直させます。仕組みは結果に納得できないときの備えを参照してください。あとの 2 つでは、エージェントの修正が終わるとタスクが再び done になり、同じルールでレビューされます。

ワークフローレベルのゲートで使えるのは、3 つの最終アクションだけです。この時点では、どのタスクにもすでに結論が出ているため、ワークフローレベルのレビューでは、結果全体についてだけ判断します。分離ブランチモードでは、承認すると、統合ブランチにマージ済みの結果がそのまま残ります。キャンセルまたは見送りにすると、統合ブランチは今回のワークフローのベースに戻ります。そのため、問題が見つかったときにエージェントに修正を続けさせたいのであれば、ワークフローレベルのゲートだけを閉じるのではなく、タスクレベルのゲートを閉じておく必要があります。たとえば、ワークフローの最後のタスクのゲートです。各アクションの使い方とオプションは、タスクとワークフローをレビューするを参照してください。

検証タスク

人が丁寧にレビューできる結果の数には限りがあります。そうなると、まず機械にひととおりチェックさせ、チェックを通った結果だけを人に回したくなります。CodeDAG には、組み込みのテストゲートがありません。CodeDAG が自分でテストを実行することはなく、自動承認もテストの結果は見ません。しかし、タスクエージェントはテストを実行できます。「すべてのテストを実行し、すべて通るまで失敗を修正してください」という指示を 1 つのタスクとして書き、チェックしたいタスクの後ろに置けば、チェックはワークフローの決まった 1 ステップになります。ワークフローを実行するたびに必ず行われ、問題が見つかればその場で修正されます。

このようなタスクを検証タスクと呼びます。「CodeDAG の仕組み」のダイヤモンド型のワークフローのタスク 4 が、その一例です。チェックの対象はテストに限りません。ビルド、型チェック、lint のほか、それまでの変更を別のエージェントにレビューさせること（一方が作業し、もう一方がチェックして修正するを参照）も、同じようにタスクとして書けます。

検証タスクも、エージェントが実行するタスクであることに変わりはありません。CodeDAG がタスクの完了を判断する基準もほかのタスクと同じで、エージェントが作業を終えたことであって、テストが通ったことではありません。エージェントが直しきれずに最後は諦めた場合でも、タスクは同じように done になり、ゲートが開いていれば、たいていそのまま自動承認されます。そのため、検証タスクのプロンプトには完了条件を明記し、結果をファイルに書くよう求めます。どのチェックを実行したか、何を修正したか、まだ通っていないものは何か、といった内容です。この記録が、人が最後に確認するものになります。分離ブランチモードでは、この記録にもう 1 つ役割があります。検証タスクは、チェックがすべて通って何も変更しなかった場合、変更を残さなかったことを理由に、止まってレビューを待つことになります。記録を書いておけば、そうはなりません。

検証タスクの後ろに、人がレビューするゲートをもう 1 つ残しておけば、まず機械がチェックし、最後に人が目を通す形になります。検証タスク自体のゲートを閉じておけば、記録を読んでまだ問題があるときに、そのまま修正を続けさせられます。あるいは、ワークフローレベルのゲートを閉じておき、結果全体について最終的な判断を下すこともできます。

レビューの結論は変更できない

最終的な結論は、いったん出すと、その実行の中では変更できません。自動承認による結論も同じです。下流のタスクが、承認された結果をもとに、すぐに作業を始めるからです。

自動承認の設定も、ワークフローを投入したあとは変更できません。そのため、自分でレビューする必要があるタスクは、投入する前に autoAccepted を none にしておきます。

変更できないのはレビューの結論だけで、コードそのものはあとからでも手直しできます。あとで問題に気づいた場合は、Git でそのタスクの変更を処理し、新しいワークフローでやり直します。方法はタスクにレビューの結論が出たあとで問題に気づいたを参照してください。