チャットや課題管理から依頼を受けるコーディングエージェントのサービスを作る

## 実行の役割ごとに仕事を1つ決め、レビュー役は読むだけにする ランタイムの各役割には、明確な責務を1つずつ割り当てます。 - メインのコーディングエージェントグラフはスレッドごとに新しいエージェントを作成し、永続状態はスレッドのサンドボックスとメタデータに保持します。 - レビューグラフは、指摘事項モデルと専用の公開アクションを使って読み取り専用のコードレビューを行います。変更、コミット、プッシュ、レビュー作成の各ツールは持たせません。 - 分析グラフは、初期構築モードと継続学習モードでリポジトリ固有のレビュー指針を作り、専用ツール1つだけを使って保存します。 - Webアプリケーションは、コードホスト、課題管理、チャットのWebhookを受け取り、一貫したスレッドを特定し、対応するグラフ実行を開始またはストリーミングします。 - ダッシュボードは、サインイン、ユーザープロファイル、チーム既定値、有効なリポジトリ、レビュースタイル管理、画面で使うスレッドAPIを所有します。 分析手順は各サンドボックスへコピーせず、バージョン管理された読み取り専用の仮想スキルとして提供します。定期的な継続改善は、初期構築が完了してから登録します。すべてのグラフエントリーポイントとアプリケーション経路を1つのランタイムマニフェストにまとめ、完全な開発ランタイムとWeb専用の小規模なプロセスを使い分けられるようにします。 ## 開発ツールを1組に決め、いちばん小さいテストから実行する 依存関係マネージャー、テストランナー、リンター、フォーマッター、型検査器、言語の最低バージョン、デプロイ先ランタイムのバージョンをそれぞれ1つ宣言します。リポジトリは、サポートする最低バージョンと、デプロイ用メタデータで固定された新しいバージョンの両方で有効でなければなりません。 次のコマンドを文書化します。 1. 開発用依存関係をインストールする。 2. グラフとWebの完全なランタイムを起動する。 3. Webアプリケーションだけを起動する。 4. 単体テスト用ディレクトリ全体を実行する。 5. 1つのテストファイルまたはテストケースを実行する。 6. ファイルを変更せずにlintとフォーマットを検査する。 7. フォーマッターと安全な自動修正を適用する。 8. 本番コードとテストコードを型検査する。 原則として単体テストを使います。統合テストには専用ディレクトリを用意し、統合テスト一式が存在しない場合は、意味が曖昧な失敗ではなく明示的な無処理として扱います。開発中は、広範なリポジトリ検査より先に、単一テストまたは最小の関連テスト一式を実行します。 ## スレッドごとにサンドボックスを1つ持ち、壊れたら作り直す スレッド識別子をキーとするプロセス内サンドボックスキャッシュを保持し、サンドボックス識別子をスレッドのメタデータに永続化します。ライフサイクルの状態を明示的に処理します。 1. サンドボックスがキャッシュにある場合は動作確認を行います。確認に失敗したら再作成し、正常な場合は認証済みネットワークプロキシを更新します。 2. メタデータに作成中の番兵値がある一方でキャッシュ済みサンドボックスがない場合は、代替を作る前に古い番兵値を解除します。 3. サンドボックスが存在しない場合は作成中の番兵値を書き込み、サンドボックスを作成し、その番兵値を実際の識別子に置き換えます。 4. メタデータに識別子がある一方でプロセスキャッシュが空の場合は再接続し、失敗したら再作成へ切り替えます。 認証済みプロキシに対応するプロバイダーでは、作成または更新のたびに、有効期間の短い新しいインストール資格情報を取得します。プロキシにコードホストとAPIの認証情報を注入させ、サンドボックスのコマンドでは実際の資格情報を保存せず、無害な代替値を使えるようにします。この機能を持たないプロバイダーでは、プロキシ経路を明示的に対象から外します。 自動化用の実行主体設定は、実行のたびに適用し直します。再利用または再接続した環境ではグローバル設定が失われることがあり、下流のデプロイ検査では、作成者の実行主体が認識されないコミットが拒否される場合があります。 ## モデル呼び出しを囲むミドルウェアを、決めた順番で動かす モデル呼び出しを囲むミドルウェアは、意図した順序で実行します。 1. ツール入力を無害化し、正規化する。 2. モデル呼び出し回数に上限を設け、上限では正常に終了する。 3. ツール例外をツールメッセージへ変換する。 4. 適用対象となる上位階層の指示を、実行ごとに1回だけファイル読み取り結果へ追加する。 5. 実行中に届いた課題またはチャットメッセージを、次のモデル呼び出し前に注入する。 6. 外部のアシスタント状態表示を更新する。 7. 空のモデル応答を、継続または完了確認用の合成ツール呼び出しへ置き換える。 8. 全体のステップ上限に達したら、送信元チャネルへ通知する。 9. サンドボックス障害が繰り返されたら、サーキットブレーカーを作動させる。 10. 別のフォールバックが設定されている場合に限り、モデルのフォールバックを追加する。 11. プロバイダー固有の不正形式の推論ブロックを、プロバイダー呼び出しの直前に取り除く。 処理を続けるためのシステム指示と空応答ガードを組み合わせ、作業が無言で終了しないようにします。範囲付きのファイル指示、メッセージキュー注入、フォールバック、サンドボックス回復が不要なレビュー用ミドルウェアは、より小さく保ちます。未使用のミドルウェア部品は、存在するだけでは有効になりません。新しいミドルウェアは、正しい位置に明示的に登録します。 ## 役割ごとに、要るツールだけを渡す カスタムツールは、小さく平坦な登録簿で管理します。メインエージェントには、許可済みのネットワーク要求、検索、課題管理操作、レビュー依頼、再開予約、チャット返信を与えられます。レビュー担当には、読み取り中心のネットワークツールに加え、指摘事項の作成、更新、一覧取得、レビュー公開だけを与えます。分析担当には、レビュー指針の保存に必要な操作だけを与えます。 汎用のファイル、シェル、検索、タスク、計画の各機能は、エージェントフレームワークに提供させます。これらのツールをカスタム登録簿で重複させないでください。 エージェント終了後の安全網に、作業の公開を任せないでください。エージェントの作業手順では、許可済みのコミット、プッシュ、レビューの作成または更新、送信元チャネルへの返信を、それぞれ明示的に実行しなければなりません。読み取り専用のレビュー担当に、これらの変更機能を継承させてはいけません。 ## モデルは決めた順で選び、資格情報は暗号化して持つ 各実行のモデルと推論強度は、次の順序で解決します。 1. 起動イベントまたは画面から渡されたスレッド単位の設定。 2. 解決されたユーザーのプロファイル上書き。 3. チームの既定値。 対応するモデル識別子、推論強度の規則、プロバイダー引数、モデル構築、フォールバック選択を一元管理します。レビューの自動作成許可などの動作フラグは、Webhookコードへ分散させず、ユーザープロファイルに保持します。 ユーザーの認可資格情報は保存時に暗号化し、実行中だけプロセス内へキャッシュします。ユーザー資格情報が使えない場合は、有効期間の短いアプリケーション用インストール資格情報へ切り替えます。同じアプリケーション資格情報を使って認証済みサンドボックスプロキシを設定しますが、生の資格情報をサンドボックス内へ永続化してはいけません。 イベントを振り分ける前に、Webhookが真正であることを検証します。コードホストの署名検査、チャット検証、課題管理の検証、ダッシュボードのサインイン処理は、それぞれの所有モジュールに保持します。 ## 続きのメッセージを、同じスレッドとサンドボックスへ戻す 外部会話の識別情報から安定したスレッド識別子を導出し、同じ課題、チャットスレッド、ブランチ、レビューへのすべての後続メッセージが、同じエージェント状態とサンドボックスへ戻るようにします。レビュー実行には別の決定的な名前空間を割り当て、スレッド種別をメタデータに記録します。 実行中にメッセージが届いたらスレッドキューへ入れ、次のモデル呼び出し前に注入します。これにより、現在の実行を放棄したり競合するエージェントを作ったりせず、継続性を維持できます。外部ユーザーが作業中、完了、ステップ上限による終了を区別できるように、状態更新をモデル呼び出しの境界に合わせます。 ## CIの失敗の自動修正は、スイッチが入っている時だけ動かす 自動修復の流れは、検査失敗、マージ競合、エージェントが作成したレビューへの対応すべきフィードバックを受けて動作できます。永続的なレビューメタデータから元のスレッドを特定し、信頼度ゲートを通した修復実行をメインエージェントグラフへ送ります。 多層の有効化を必須にします。 - ユーザー単位の自動化フラグ。 - リポジトリのオプトイン。 - レビュー単位のオンまたはオフ上書き。 ベースブランチにすでに存在する失敗、人間によるコミット、同じ先頭リビジョンの重複処理、別の修復実行中のまとめ待ち、厳格なループ上限に対するスキップ規則を一元管理します。定期監視は、見逃されたイベントを探すために、エージェントが作成した未完了レビューを走査する補助経路としてのみ使います。 ## 新しいプロバイダーやツールは決まった登録先に足し、非同期のまま保つ サンドボックスプロバイダーは、その統合モジュールに追加し、プロバイダーのファクトリーマップへ登録します。カスタムツールはツールパッケージに追加して1度だけエクスポートし、それを必要とする役割固有のツール一覧だけに含めます。ミドルウェアは専用モジュールに追加してエクスポートし、順序付きスタック内の意図した位置に配置します。ダッシュボードのエンドポイントはマウント済みルーターへ、新しいグラフはランタイムマニフェストへ追加します。 非同期専用のアプリケーションは、非同期のまま維持します。並行する同期実装を作らないでください。インターフェースが許す場合は同期メソッド自体を省きます。抽象契約によって必要な場合は、未対応操作エラーを送出する最小限のメソッドだけを用意します。 原則として単体テストを使い、実際の統合には専用の統合テスト領域を使い、コメントは最小限にします。コメントには実装を言い換えるのではなく、自明でない理由や順序上の制約を書きます。