Orchestrating AI Code Review at scale｜大規模なAIコードレビューの運用

コードレビュー（code review）はバグの発見や知識共有に優れた仕組みですが、エンジニアリングチームのボトルネック（bottleneck）になる最も確実な方法の一つでもあります。マージリクエスト（merge request）がキューに溜まり、レビュアーは最終的にコンテキストスイッチ（context switch）を起こして差分（diff）を読み、変数名に関するいくつかの些細な指摘を残し、著者がそれに対応し、そのサイクルが繰り返されます。社内プロジェクト全体を通じて、最初のレビュー待ち時間の中央値はしばしば数時間単位で計測されていました。 AIコードレビュー（AI code review）の実験を始めた当初、私たちはおそらく多くの人が取る道を選びました。いくつかの異なるAIコードレビューツールを試したところ、これらのツールの多くがかなりよく機能し、さらに多くのツールが良い程度のカスタマイズ性と設定可能性（customisation and configurability）を提供していることが分かりました！しかし残念ながら、繰り返し浮上した唯一のテーマは、Cloudflareのような規模の組織には柔軟性とカスタマイズ性が十分でなかったという点でした。 そこで、私たちは次に最も obvious な道、つまり Git diff（git diff）を取得し、半ば未完成のプロンプト（prompt）に放り込んで、大規模言語モデル（large language model / LLM）にバグを探すよう依頼する道に進みました。結果は予想どおり非常にノイズが多く、曖昧な提案の洪水、幻覚的な構文エラー、すでにエラーハンドリングが実装されている関数に対する「エラーハンドリングの追加を検討してください」という親切な助言が溢れていました。私たちはすぐに、単純な要約アプローチでは、特に複雑なコードベースにおいては望む結果が得られないことに気づきました。 ゼロから単一の巨大なコードレビューエージェント（monolithic code review agent）を構築するのではなく、私たちはオープンソースのコーディングエージェントである OpenCode を中心に、CIネイティブ（CI-native）なオーケストレーションシステム（orchestration system）を構築することを決めました。現在、Cloudflareのエンジニアがマージリクエスト（merge request）を作成すると、連携したAIエージェントによる多彩な buffet（スモーグスボード）からの初期チェックが行われます。巨大で汎用的なプロンプトを一つのプロモデルに依存するのではなく、セキュリティ、パフォーマンス、コード品質、ドキュメント、リリース管理、社内エンジニアリングコデックスへの準拠をカバーする最大7つの専門レビュアーを起動します。これらのスペシャリストはコーディネーターエージェント（coordinator agent）によって管理され、その発見の重複排除を行い、問題の実際の重大度を判断し、単一の構造化されたレビューコメントを投稿します。 私たちはこのシステムを社内にて、数万件に及ぶマージリクエスト（merge requests）に対して運用しています。クリーンなコードは承認し、実버그を驚くべき精度でフラグ付けし、本格的な深刻な問題やセキュリティ脆弱性（security vulnerabilities）が見つかった場合はマージを積極的にブロックします。これは、Code Orange: Fail Smallの一環としてエンジニアリングレジリエンス（engineering resiliency）を向上させる多くの方法の一つに過ぎません。 本記事では、その構築方法、採用したアーキテクチャ（architecture）、そしてCI/CDパイプライン（CI/CD pipeline）のクリティカルパス（critical path）にLLMを配置しようとする際、特にコードをリリースしようとするエンジニアの邪魔をすることになる際に直面する具体的なエンジニアリング問題について深く掘り下げています（deep dive）。 アーキテクチャ：プラグインを月まで 数千のリポジトリで実行される内部ツールの構築において、バージョン管理システム（version control system）やAIプロバイダーをハードコーディングすることは、6ヶ月後に全体を書き直すことになることを確実にする最良の方法です。私たちは今日GitLabをサポートする必要があり、明日は誰が何を使うか分かりませんし、異なるAIプロバイダーや内部基準要件とも併存させる必要があります。その際、どのコンポーネントも他者の存在を知らなくて済むようにする必要があります。 システムは、コンポーザブルなプラグインアーキテクチャ（composable plugin architecture）を基盤として構築されており、エントリポイントがすべての設定をプラグインに委譲します。それらのプラグインを組み合わせて、レビューの実行方法を定義します。以下は、マージリクエスト（merge request）がレビューをトリガーした際の実行フローです： ![image](https://cf-assets.www.cloudflare.com/zkvhlag99gkb/7mAft27PsDQnNSNCvF7waU/fdd2c1c448e1863e34f71c124fa85ea1/BLOG-3284_2.jpg) 各プラグインは、3つのライフサイクルフェーズ（lifecycle phases）を持つ`ReviewPlugin`インターフェースを実装しています。ブートストラップフック（Bootstrap hooks）は並列で実行され、致命的ではありません。つまり、テンプレートのフェッチに失敗しても、レビューはそのまま続行されます。コンフィグアフフック（Configure hooks）は順次実行され、致命的です。VCSプロバイダー（VCS provider）がGitLabに接続できない場合、ジョブを続行する意味がないためです。最後に、`postConfigure`は設定の組み立て後に実行され、リモートモデルのオーバーライド取得などの非同期タスクを処理します。 `ConfigureContext`は、プラグインがレビューに影響を与えるための制御されたインターフェースを提供します。プラグインはエージェントの登録、AIプロバイダーの追加、環境変数の設定、プロンプトセクションの注入、細粒度のエージェント権限の変更を行うことができます。どのプラグインも最終的な設定オブジェクトに直接アクセスできません。プラグインはコンテキストAPI（context API）を通じて貢献し、コアアセンブラ（core assembler）がそれらをすべてマージしてOpenCodeが消費する`opencode.json`ファイルを作成します。 この分離により、GitLabプラグインはCloudflare AI Gatewayの設定を読み取らず、CloudflareプラグインもGitLab APIトークンについて一切知りません。すべてのVCS固有の結合（VCS-specific coupling）は、単一の`ci-config.ts`ファイル内に隔離されています。 典型的な内部レビューにおけるプラグインリストは以下の通りです： Plugin Responsibility @opencode-reviewer/gitlab GitLab VCSプロバイダー、MRデータ、MCPコメントサーバー @opencode-reviewer/cloudflare AI Gateway設定、モデルティア、フェイルバックチェーン @opencode-reviewer/codex エンジニアリングRFCに対する内部コンプライアンスチェック @opencode-reviewer/braintrust 分散トレーシングと観測性（distributed tracing and observability） @opencode-reviewer/agents-md リポジトリのAGENTS.mdが最新であることを検証 @opencode-reviewer/reviewer-config Cloudflare Workerからのレビューごとのリモートモデルオーバーライド @opencode-reviewer/telemetry 投げっぱなし方式（fire-and-forget）のレビュー追跡 OpenCodeの内部での活用方法 いくつかの理由から、OpenCodeをコーディングエージェント（coding agent）として選択しました： 社内で広く使用しており、すでにその動作原理に非常に精通していること これはオープンソースであるため、機能やバグ修正をアップストリーム（upstream）に貢献でき、問題を見つけた際に調査も非常に容易です（執筆時点でCloudflareのエンジニアは45件以上のプルリクエスト（pull requests）をアップストリームにマージしています！） 優れたオープンソースのSDK（Software Development Kit）を備えており、完璧に動作するプラグインを容易に構築できます。 しかし何より重要なのは、テキストベースのユーザーインターフェースやデスクトップアプリをその上のクライアントとして配置し、サーバーファーストの構造になっている点です。これは私たちの必須条件でした。CLI（Command-Line Interface）インターフェースを無理やり操作するのではなく、セッションをプログラムで作成し、SDK経由でプロンプトを送信し、複数の並行セッションからの結果を収集する必要があったためです。 オーケストレーションは、2つの明確なレイヤーで動作します。 コーディネータープロセス：Bun.spawnを使用してOpenCodeを子プロセスとして起動します。コマンドライン引数ではなくstdin（標準入力）経由でコーディネータープロンプトを渡しています。大量のログを含む巨大なマージリクエストの説明をコマンドライン引数として渡そうとしたことがあるなら、LinuxカーネルのARG_MAX制限にぶつかったことがあるはずです。非常に大きなマージリクエストを対象としたCI（Continuous Integration）ジョブのわずかな割合でE2BIGエラーが発生し始めた際、私たちはこれをすぐに学びました。プロセスは--format jsonオプションで実行されるため、すべての出力がstdout（標準出力）上でJSONL（JSON Lines）イベントとして到着します。 ```javascript const proc = Bun.spawn( ["bun", opencodeScript, "--print-logs", "--log-level", logLevel, "--format", "json", "--agent", "review_coordinator", "run"], { stdin: Buffer.from(prompt), env: { ...sanitizeEnvForChildProcess(process.env), OPENCODE_CONFIG: process.env.OPENCODE_CONFIG_PATH ?? "", BUN_JSC_gcMaxHeapSize: "2684354560", // 2.5 GB heap cap }, stdout: "pipe", stderr: "pipe", }, ); ``` レビュープラグイン：OpenCodeプロセス内では、ランタイムプラグインがspawn_reviewersツールを提供しています。コーディネーターLLM（Large Language Model）がコードレビューのタイミングと判断すると、このツールを呼び出し、OpenCodeのSDKクライアントを通じてサブレビュアーセッションを起動します。 ```javascript const createResult = await this.client.session.create({ body: { parentID: input.parentSessionID }, query: { directory: dir }, }); // Send the prompt asynchronously (non-blocking) this.client.session.promptAsync({ path: { id: task.sessionID }, body: { parts: [{ type: "text", text: promptText }], agent: input.agent, model: { providerID, modelID }, }, }); ``` 各サブレビュアーは、独自のエージェントプロンプトを持つ個別のOpenCodeセッション内で実行されます。コーディネーターはサブレビュアーが使用するツールを閲覧したり制御したりすることはありません。サブレビュアーは必要に応じてソースファイルの読み取り、grepの実行、コードベース内の検索を自由に行い、完了すると結果を構造化XML（structured XML）として返すだけです。 JSONLとは何で、私たちはそれを何に使用しているのでしょうか？ このようなシステムを扱う際によく直面する大きな課題の一つは、構造化ログ（structured logging）の必要性です。JSON は優れた構造化形式ですが、有効な JSON ブロブ（JSON blob）として成立させるには、すべての要素を「閉じる」必要があります。アプリケーションが正常に終了する前に早期に終了し、すべての要素を閉じて有効な JSON ブロブをディスクに書き込む機会がない場合、これは特に問題となります。そして、デバッグログ（debug logs）が最も必要とされるのは、往々にしてそのような時です。 これが私たちが JSONL（JSON Lines）を使用する理由です。その名が示す通り、これは各行が有効で自己完結型の JSON オブジェクトであるテキスト形式です。標準的な JSON 配列とは異なり、最初のエントリを読むために文書全体を解析する必要はありません。1行を読み、解析し、次に進みます。つまり、巨大なペイロードをメモリにバッファリングすることを心配したり、子プロセス（child process）がメモリエラーを起こしたために到着しないかもしれない閉じ括弧 `]` を期待したりする必要がありません。 実際の実装は以下のようになります： Stripped: authorization, cf-access-token, host Added: cf-aig-authorization: Bearer cf-aig-metadata: {"userId": ""} 構造化出力を長時間実行プロセスから解析する必要がある CI システム（CI system）は、最終的に JSONL のような形式に行き着きますが、私たちは既存のものを再発明したくありませんでした。（OpenCode はすでにこれをサポートしています！） The streaming pipeline 協調者（coordinator）の出力はリアルタイムで処理しますが、ディスクを低速だが痛ましい `appendFileSync` による書き込み処理の死から守るため、100行（または50ms）ごとにバッファリングしてフラッシュします。 ストリームが流れ込む際に特定のトリガーを監視し、コスト追跡用の `step_finish` イベントからトークン使用量（token usage）を抽出し、エラーイベントを使用してリトライロジック（retry logic）を開始します。また、出力の切り捨て（output truncation）にも注意を払います。`step_finish` で `reason: "length"` が返ってきた場合、モデルが `max_tokens` 制限に達して途中の文で切り捨てられたことがわかるため、自動的にリトライする必要があります。 私たちが予測しなかった運用上の頭痛の種の一つは、Claude Opus 4.7 や GPT-5.4 といった大規模で高度なモデルが、問題について熟考するのにかなりの時間を要することがある点です。ユーザーにとっては、これがまさにハングアップしたジョブ（hung job）のように見えます。私たちは、レビューアーが意図通りに動作していないとユーザーから苦情が寄せられ、ジョブが頻繁にキャンセルされることに気づきましたが、実際にはバックグラウンドで正常に動作していました。これを防ぐため、30秒ごとに「Model is thinking... (Ns since last output)」を出力する非常にシンプルなハートビートログ（heartbeat log）を追加したところ、この問題はほぼ完全に解消されました。 Specialised agents instead of one big prompt 単一のモデルにすべてのレビューを依頼するのではなく、ドメイン固有のエージェント（domain-specific agents）にレビューを分割しました。各エージェントには、何を検索すべきか、そして何より重要なのは何を無視すべきかを正確に指示する、スコープを限定したプロンプト（tightly scoped prompt）が設定されています。 例えば、セキュリティレビュアー（security reviewer）には、「実害があるか、具体的に危険な」問題のみをフラグとして報告するよう明確に指示されています。 翻訳全文 ## 対象とするフラグ - インジェクション脆弱性（SQLインジェクション、XSS、コマンドインジェクション、パストラバーサル） - 変更されたコードにおける認証/認可のバイパス - ハードコーディングされたシークレット、資格情報、またはAPIキー - 安全でない暗号化の使用 - 信頼境界における信頼できないデータに対する入力検証の欠如 ## フラグ対象外とする事項 - あり得ない前提条件を必要とする理論的なリスク - 主要な防御策が十分である場合のディフェンス・イン・デプス（Defense-in-depth）に関する提案 - このMR（Merge Request）が影響しない、変更されていないコードの問題 - 「ライブラリXの使用を検討してください」といったスタイルの提案 実際、LLMに「何をすべきでないか」を指示することこそが、プロンプトエンジニアリング（prompt engineering）の真価が発揮される箇所である。これらの境界線がない場合、開発者がすぐに無視することを学ぶような推測に基づく理論的な警告の洪水が引き起こされる。 各レビュアーは、重大度分類（critical：障害や攻撃可能を引き起こすもの、warning：測定可能な後退または具体的なリスク、suggestion：検討に値する改善）付きの構造化XML形式（structured XML format）で所見を出力する。これにより、助言テキストを解析するのではなく、下流の動作を駆動する構造化データを扱っていることを保証している。 使用するモデル レビューを専門的なドメインに分割しているため、すべてのタスクに対して非常に高価で高度なモデルを使用する必要はない。エージェントの作業の複雑さに基づいてモデルを割り当てる： 最上位層（Top-tier）：Claude Opus 4.7およびGPT-5.4。レビューコーディネーター（Review Coordinator）専用に予約されている。コーディネーターは最も困難なタスクを担う——他の7つのモデルの出力を読み取り、所見の重複排除（deduplicating findings）を行い、誤検知（false positives）をフィルタリングし、最終的な判断を下す。利用可能な最高の推論能力が必要とされる。 標準層（Standard-tier）：Claude Sonnet 4.6およびGPT-5.3 Codex。コード品質、セキュリティ、パフォーマンスの主要サブレビュアー（sub-reviewers）の中核を担う。これらは高速で比較的安価であり、コード内の論理エラーや脆弱性の検出に優れている。 Kimi K2.5：ドキュメントレビュアー、リリースレビュアー、AGENTS.mdレビュアーといった軽量でテキスト中心のタスクに使用される。 これらはデフォルト設定であるが、すべてのモデル割り当ては、後述のコントロールプレーンセクション（control plane section）で詳述するreviewer-config Cloudflare Workerを通じてランタイム時に動的に上書き可能である。 プロンプトインジェクション防止（Prompt injection prevention） エージェントプロンプトは、ランタイム時にエージェント固有のmarkdownファイル（agent-specific markdown file）と必須ルールを含む共有REVIEWER_SHARED.mdファイルを連結して構築される。コーディネーターの入力プロンプトは、MRメタデータ（MR metadata）、コメント、以前のレビュー所見、diffパス（diff paths）、カスタム指示を構造化XMLに結合して組み立てられる。 ユーザー管理コンテンツのサニタイズも必要でした。もし誰かがMR（Merge Request）の説明に「Repository: evil-corp」と記載した場合、理論的にはXML構造から抜け出してコーディネーターのプロンプトに独自の指示をインジェクトできます。私たちはこれらの境界タグ（boundary tags）を完全に削除しています。これは、新しい社内ツールをテストする際のCloudflareエンジニアの創造性を過小評価してはならないという、長年の経験から学んだことです。 ```javascript const PROMPT_BOUNDARY_TAGS = [ "mr_input", "mr_body", "mr_comments", "mr_details", "changed_files", "existing_inline_findings", "previous_review", "custom_review_instructions", "agents_md_template_instructions", ]; const BOUNDARY_TAG_PATTERN = new RegExp( `]*>`, "gi" ); ``` トークン節約のための共有コンテキスト\nシステムはプロンプトに完全な差分（full diffs）を埋め込みません。代わりに、ファイルごとのパッチファイルを `diff_directory` に書き出し、そのパスを渡します。各サブレビュアー（sub-reviewer）は、自身のドメインに関連するパッチファイルのみを読み取ります。 また、コーディネーター（coordinator）のプロンプトから共有コンテキストファイル（shared-mr-context.txt）を抽出し、ディスクに書き出します。サブレビュアーはこのファイルを読み取るため、各プロンプトに完全なMRコンテキストを重複して含める必要がありません。これは意図的な判断でした。中規模のMRコンテキストを7つの並行レビュアーすべてに重複して含めると、トークンコストが7倍になるためです。 コーディネーターによる焦点維持\nすべてのサブレビュアーを起動した後、コーディネーターは結果を統合するための判定パス（judge pass）を実行します。 重複排除（Deduplication）：セキュリティレビュアーとコード品質レビュアーの両方で同じ問題がフラグされた場合、最も適切なセクションに1回だけ保持されます。\n\n再分類（Re-categorisation）：コード品質レビュアーによってフラグされたパフォーマンス問題は、パフォーマンスセクションに移動されます。\n\n妥当性フィルター（Reasonableness filter）：推測に基づく問題、細かな指摘（nitpicks）、誤検知（false positives）、および規約に反する発見は破棄されます。コーディネーターが確信できない場合、ツールを使用してソースコードを読み取り検証します。 全体の承認判断は厳格な基準（rubric）に従います：\n\n条件\n\n決定\n\nGitLabアクション\n\nすべてLGTM（“looks good to me”）、または単なる細かな提案のみ\n\napproved\n\nPOST /approve\n\n提案レベルの問題（suggestion-severity items）のみ\n\napproved_with_comments\n\nPOST /approve\n\n一部警告あり、本番環境リスク（production risk）なし\n\napproved_with_comments\n\nPOST /approve\n\nリスクパターン（risk pattern）を示唆する複数の警告\n\nminor_issues\n\nPOST /unapprove（以前のボット承認を取り消し）\n\n重大な問題、または本番環境の安全リスク（production safety risk）\n\nsignificant_concerns\n\n/submit_review requested_changes（マージブロック / block merge） 承認に明確に偏った基準であり、それ以外はクリーンなMR内の単一の警告でもブロックではなく `approved_with_comments` として承認されることを意味します。 本システムはコードをデプロイするエンジニアの間に直接位置する生産環境（production system）であるため、エスケープハッチ（escape hatch：緊急回避策）を必ず備えるよう設計しました。人間のレビュアーが「break glass（緊急解除）」とコメントすると、AIの判定結果にかかわらずシステムが強制的に承認を行います。時にはホットフィックス（hotfix：緊急修正パッチ）を即座にリリースする必要がある場合もあり、システムはレビュー開始前にこの上書き操作を検知するため、テレメトリ（telemetry：運用データ収集）で追跡可能であり、潜在的なバグやLLM（大規模言語モデル）プロバイダーの障害に巻き込まれる心配がありません。 リスクティア：誤字修正にドリームチームを送る必要はない README内の1行の誤字修正をレビューするのに、Opusティア（Opus-tier：最高級モデル）のトークンを消費する7つの並列AIエージェントが必要ありません。システムは、diff（差分）の規模と性質に基づき、すべてのMR（Merge Request：マージリクエスト）を3つのリスクティアのいずれかに分類します。 // packages/core/src/risk.ts からの簡略化コード function assessRiskTier(diffEntries: DiffEntry[]) { const totalLines = diffEntries.reduce( (sum, e) => sum + e.addedLines + e.removedLines, 0 ); const fileCount = diffEntries.length; const hasSecurityFiles = diffEntries.some( e => isSecuritySensitiveFile(e.newPath) ); if (fileCount > 50 || hasSecurityFiles) return "full"; if (totalLines = 100 || fileCount > 50) return "standard"; return "full"; } // テーブル内容の翻訳（原文の構造を保持） | リスクティア | 条件 | レビュー担当者数 | 専門家の範囲 | |---|---|---|---| | trivial（軽微） | 100行未満かつ50ファイル以下 | 2名 | 全専門職（セキュリティ、パフォーマンス、リリースを含む） | | standard（標準） | 100行以上または50ファイル超 | 7名以上 | 全専門職（セキュリティ、パフォーマンス、リリースを含む） | The trivial tier also downgrades the coordinator from Opus to Sonnet, for example, as a two-reviewer check on a minor change doesn't require an extremely capable and expensive model to evaluate. diffフィルタリング：ノイズの除去 エージェントがコードを参照する前に、diffはロックファイル、ベンダー依存パッケージ（vendored dependencies）、縮小化されたアセット（minified assets）、ソースマップ（source maps）などのノイズを除去するフィルタリングパイプラインを通ります。 const NOISE_FILE_PATTERNS = [ "bun.lock", "package-lock.json", "yarn.lock", "pnpm-lock.yaml", "Cargo.lock", "go.sum", "poetry.lock", "Pipfile.lock", "flake.lock", ]; const NOISE_EXTENSIONS = [".min.js", ".min.css", ".bundle.js", ".map"]; 生成ファイルについても、先頭数行をスキャンして `// @generated` や `/* eslint-disable */` などのマーカーを検出し、フィルタリングします。ただし、データベースマイグレーション（database migrations）はこのルールから明示的に除外しています。マイグレーションツールは、レビューが絶対に必要なスキーマ変更を含んでいるにもかかわらず、ファイルを生成済みとしてマークすることが多いためです。 `spawn_reviewers`ツール：並列オーケストレーション

大規模なAIコードレビューの運用

背景や根拠まで確認しますか？

このニュースを、実務の判断につなげる

調べる

選ぶ

サイト