エージェントの役割

Coroidでは汎用のエージェントは使用しません。タスクの各ステージはpull requestへの記述からのプロセスは、限定的な役割と意図的に制限されたツールセットを持つエージェントが処理します。

この制限こそが重要なのです。コードを書けないエージェントは、誤ってコードを書くことがありません。

役割#

役割	ステージ	コードを変更可能
Architect	仕様と計画	不可
Developer	ビルド	可能
QA	検証	不可
Reviewer	レビュー	不可
Webテスター	検証、ブラウザフロー	不可
Explorer	調査、任意のステージ	不可
依存関係分析ツール	分析	不可

最初の4つは、各タスクで利用されるデリバリーエージェントです。標準モードでは、以下の順序で実行されます：

アーキテクト → デベロッパー → QA → レビュー

コーディネーターモードでは、タスクの進行に合わせてコーディネーターが実行順序を決定します。両方のモードについて以下で説明します。

リポジトリ内のファイルを変更できる役割はデベロッパーのみです。それ以外のエージェントはすべて、読み取り、実行、報告、または後続作業の作成のみを行います。

タスクの実行方法は2通り#

タスクは2つのモードのいずれかで実行されます。そのAIプロファイルとご自身のデプロイメント設定によって、どちらのモードで実行されるかが決まります。

コーディネーターモード。アーキテクトは計画を渡して作業を終えるわけではありません。コーディネーターとしてタスクに留まり続けます。計画完了後、コーディネーターは開発者に指示を出し、報告を待ちます。その後、構築された内容を検証するようQAに依頼し、QAの検証を通過した内容をレビューするようレビュアーに依頼します。各報告を受けた後、コーディネーターが次の手順を決定します：検出結果を開発者に戻す、質問に答える、計画を修正する、またはタスクを完了させる。再作業もコーディネーターにとっては新たな実行履歴を作成するのではなく、単なる追加ステップに過ぎません。

標準モードプラットフォームはタスクを4つのエージェント間で固定の順序で処理し、チェックに失敗した場合は開発者に戻します。マージコンフリクトの解消など、常にこの方法で実行される作業もあり、コーディネーターモードが利用できない場合のフォールバックとして標準モードが適用されます。

どちらのモードでも同じエージェントが作業を担い、同じ制限と同じゲートが適用されます。違いは次のステップを選択するのが標準モードではプラットフォームであり、コーディネーターモードではコーディネーターである点です。

コーディネーター#

コーディネーターは計画エージェントであり、タスクに専念します。このエージェントはコードベースを読み取ることはできますが変更することはできないため、実行する作業はすべて指示出しのみとなります。

コーディネーターの役割#

• プランコーディネーターはリポジトリを調査した後、作業が成功したかどうかを判断する受け入れ基準を含むプランを保存します。
• 委任コーディネーターは一度に1人のエージェントと連携します。指示には目標や特に注意が必要な受け入れ基準、そして作業結果を返す際の具体的な修正内容が含まれます。エージェントが作業している間、コーディネーターは待機し、モデルの処理時間は使用しません。
• 質問に回答意思決定に直面したエージェントはコーディネーターに質問できます。コーディネーターはその決定内容と理由を回答し、質問が人間の判断を待つことなく解決されます。
• 対応QAで作業が失敗した場合やレビュアーが変更を求めた場合、 コーディネーターは修正内容を開発者に送り、QAが新しいバージョンを検証します。
• タスクを終了します。コーディネーターがタスクを完了させるか、失敗した場合はその理由を伝えます。

コーディネーターができないこと#

コーディネーターは指示を出すだけで、判断はしません。プラットフォームがこれらの制限を強制するため、 コーディネーターの判断に依存しません：

1. 判定はQAとレビュアーが下します。判定を下すのはQAとレビュアーのみで、 それぞれが独自の結果を出します。コーディネーターの指示には判定を含める余地がなく、 コーディネーターがチェックを合格とマークすることもできません。
2. 完了には条件を満たす必要があります。タスクが完了するのは、QAがリリース予定の正確なバージョン（変更がない場合は現状のコード）を検証し、レビューが必要な場合にはレビュアーがそのバージョンを承認した時のみです。QA実行後にブランチが変更された場合、完了は拒否され、新しいバージョンは再びQAに送られます。
3. 再作業には上限があります。各エージェントはタスクごとに開始できる回数が限定されており、 プランの修正も数回までしかできません。ステップ数や総実行時間にも上限があります。 上限に達すると、コーディネーターはタスクを完了または失敗させるしかありません。
4. 待機にも期限があります。すべての待機には期限が設定されています。

コーディネーターが管理するタスクは、3つのいずれかの結果に終わります：あなたが承認するためのpull request、コードがすでにタスクの要求通りに動作しているため変更の必要がないことを示すQAの確認結果、または失敗理由が記載されたタスクです。担当エージェントが「完了」と宣言しただけでは終了しません。

コーディネーターが選択できるルート#

コーディネーターはタスクが各ゲートを通過する方法を決定します。上記のゲートはすべてのルートで共通です。

• 完全なルート計画立案、構築、検証、レビュー、完了。これがコーディネーターが別のルートを選ばない限りのタスクの実行手順です。
• 作業を差し戻す処理QAで作業が不合格になるか、レビュアーが変更を求めた場合、修正内容は開発者に戻されます。新しいバージョンが完了するには、再度QAを通過する必要があります。以前のバージョンでの合格は新しいバージョンには引き継がれません。
• 既に完了済みコードがすでにタスクの要求通りに動作している場合、コーディネーターは何も構築せずに、受入基準に基づいて変更のないコードをQAに検証させることができます。QAが合格し、レビューが必要な場合にはレビュアーが承認すれば、マージするものがないためpull requestなしでタスクは完了します。QAの検証結果がそのまま最終結果となります。このルートは、実行中に変更が生じた時点で閉じられます。そうでなければ、リリース対象外のコードが合格してしまうからです。

2つの短縮ルートはオプションです。Coroidはデフォルトでこれらを使用しません。これらはコーディネーターのルートを変えるだけで、ゲート自体は変わりません。

• 簡易変更既知の場所にある小さな修正の場合、コーディネーターは簡略化された計画を立て、変更が適用されるファイル名を明記した具体的な指示を開発者に出します。開発者はより少ないステップ数で作業し、それらのファイル以外を変更した場合はQAおよびレビュアーに報告されます。
• 限定再検証QAまたはレビュアーが発見した問題に対する小さな修正後、QAはその検出結果とプロジェクトのテストから再検証を開始します。ただし、全体の新しいバージョンに対する判定は依然として出されます。

レビュアーが必要な場合#

デフォルトでは、単独で実行されるタスクは常にレビュアーを経由します。コーディネーターがどのようなルートを選んでも、変更が不要な場合を含め、QAが合格したバージョンをレビュアーが承認するまでタスクは完了できません。レビューがなくてもQAによる検証は必須であり、レビューはQAの合格を代替しません。計画の一部であるタスクは、該当するレーンに定められたルールに従います。

Coroidにはオプションのリスクベースポリシーもありますが、デフォルトでは有効になっていません。このポリシー下では、変更が小規模で一般的な場合、単独で実行されるタスクはレビュアーなしで完了できることがあります。ただし、以下の場合にはレビュアーが依然として必要です：

• タスクで既にレビュアーの作業が始まっている場合、またはプロジェクトのレビュー規則や組織のQuality Graphでレビュアーが求められている場合；
• 変更が認証、セッション、権限、シークレット、暗号処理、データベースの移行、ビルド・デプロイ設定、依存関係ファイル、または外部サービスと連携するコードに影響を及ぼす場合；
• 変更が大規模（デフォルトでは変更行数が80行を超える場合）であるか、バイナリファイル、シンボリックリンク、サブモジュールを含む場合；
• Coroidはポリシーや変更内容自体を読み取ることはできません。疑わしい場合にはレビュアーが必須となります。

何も変更しない場合、レビュアーは不要です。この判断はコーディネーターではなくコードが行い、コーディネーターがそれを無視することはできません。pull requestの説明の末尾には、どのように判断されたかとその理由が記載されており、「レビュアーが必要」または「レビュアーは不要」で始まります。

アーキテクト#

あなたの説明を仕様書にし、仕様書をプランに変換します。プランを実際のコードベースに合わせるためにコードベースを参照しますが、 コードは記述しません。

その出力物はビルド開始前にあなたが承認するものです。コーディネーターモードでは、 このエージェントが引き続きコーディネーターとして機能します。

開発者#

作業を実行します：関連するコードを読み取り、変更を加え、テストを作成または更新し、 ローカルワークスペースで通過するまで実行します。

「レビュアーが検出結果を返すと、開発者がそれに対応する役割です。コーディネーターモードでは、 コーディネーターが修正内容とともに検出結果を開発者に渡します。

QA#

コードを記述したエージェントとは独立して検証を実行します。つまり、あなたのテストスイート、 プロジェクトに設定された品質ゲート、仕様書に記載された受け入れ基準が対象です。

QAは判定を報告します。発見した問題を修正するのではなく、失敗した内容は開発者に開発者による再作業として処理されます。

レビュアー#

完成した差分を読み取り、検出結果を生成し、組織で設定されたレビュー規則を適用します。 検出結果は開発者への再作業として送られるか、あなたのためのpull requestに添付されます。

ウェブテスター#

実際のブラウザを使ってアプリケーションのプレビュー版を操作し、エンドツーエンドのユーザーフローを確認します。 コードだけでは挙動に関する断言ができない場合に使用されます。

エクスプローラー#

読み取り専用の調査役割です。他のエージェントが自分のコンテキストにすべてを読み込むことなく、 コードベースに関する質問に答えるために利用します。「認証処理はどこで行われるか」「この関数を呼び出すのは何か」などです。

依存関係分析器#

依存関係や変更がコードベース全体、およびクロスプロジェクト依存関係が設定されているプロジェクト間でどのように波及するかを調査します。

この分離が重要な理由#

このように作業を分割することで、以下の4つの特性が得られます：

1. 検証は独立して行われます。作業をチェックするエージェントはそれを記述したエージェントではないため、 結果に対する利害関係がありません。
2. 影響範囲は限定されます。コード記述ツールを持つのは開発者役割のみのため、 レビューや分析での失敗がリポジトリを破損することはありません。
3. 各役割に適したモデルが実行されます。計画立案には幅広い知識が求められ、コンパイル可能なコードを記述するには別の能力が必要です。 AIプロファイルはまさにこの理由から、役割ごとに1つのモデルを保持しています。
4. 作業の完了は担当エージェントではなく、チェック項目によって決定されます。コーディネーターモードでは、タスクを管理するエージェントはQA担当者およびレビュアーの承認なしには作業を終了できません。

次へ#

に戻るタスクがどのようにしてpull requestになるかこれらのロールが対応するステージについて、またはCoroidとは何かより簡潔な概要についてはこちらをご覧ください。