AIレビューのコメント一つでマージが止まり始めたら

最初はAIコードレビューがかなり頼もしく感じられます。人が見落とした社内ルールを見つけ、根拠となる文書まで添えてくれるからです。しかし、そのコメントを必須チェックにつないだ瞬間、文脈を読み違えた判定も実際のマージブロックになります。開発者はルールに従うより、チェックを回避する方法から探し始めるかもしれません。

Cloudflareはこの問題をモデル性能だけで解決しませんでした。開発標準をRFCとして管理し、文書が承認された状態と自動ブロックに使える状態を分離しています。承認済みのルールはまず非ブロッキングの推奨として表示し、別途執行状態になったRFCで満たされていない MUST だけを、承認保留やマージブロックに使います。

この事例から得るべきものは、巨大なAIレビューシステムではありません。AIの意見を追跡し、異議を申し立てられるように、ルールごとに要求レベル、安定したID、適用範囲、原文、執行状態を付ける運用構造です。

1万6,000件より先に集計範囲を読むべきです

Cloudflareは2026年8月に公開した記事の導入部で、直前の4か月間にAIコードレビューアーが標準からの逸脱を約25万件指摘し、1万6,000件のマージを防いだと明らかにしました。しかし詳細節では、Codex導入以降に約23万件を指摘し、約1万6,000件で承認を保留したと表現しています。 二つの集計の開始日と対象範囲が同じかは公開されていないため、一つの精密な成果数値として合わせて読むべきではありません。

検知件数は品質改善件数ではありません。

マージリクエストの総数またはユニーク数、同じ変更に対する繰り返しの判定、誤検知率、開発者の修正受け入れ率は公開されていません。この事例はAIレビューの精度を証明するものというより、多数の判定を開発フローにつなぐ際にどのような執行構造が必要かを示す運用事例に近いものです。

仕様レビューの数値も同じように見る必要があります。CloudflareのAI仕様レビューアーは、2026年5月初めから記事公開時点までに公開状態のユニークな仕様約600件をレビューし、修正後の再実行などを含めて3,200回超実行されました。検出事項の重大度構成はmajorが65%、minorが29%、criticalが6%でしたが、検出総数は公開されておらず、この比率も精度や実際の欠陥防止率を意味しません。

承認と執行は別のスイッチです

Cloudflare CodexでRFCが approved になると、AIレビューアーは関連する違反を知らせられますが、結果は非ブロッキングです。RFCが別の段階で enforced に昇格して初めて、満たされていない MUST が重大度に応じて承認保留やブロックにつながります。 誰が昇格を承認するのか、どの程度の誤検知率や観察期間が必要なのかは公開されていません。

ルールの状態AIレビューの動作チームが別途決めること
approved根拠のある非ブロッキングの推奨適用範囲と繰り返し発生する例外の確認
enforced満たされていないMUSTを承認保留・ブロックに使用昇格権限、異議申し立て、ブロック解除の経路

MUST と SHOULD も同じ命令ではありません。RFC 2119ではMUSTは絶対的な要件であり、SHOULDは特定の状況で逸脱する正当な理由があり得るものの、その影響を十分に理解して慎重に検討すべきレベルです。強い要求表現は、相互運用性や危害の防止に実際に必要な場合に慎重に使うべきです。 すべてのベストプラクティスをMUSTに変えても執行力が強くなるのではなく、ブロック理由が増えるだけになるかもしれません。

Googleの公開コードレビュー指針も、完璧さよりコードベースの継続的な改善を優先し、重要でない意見には任意であることを示すよう勧めています。 AIレビュー画面でも必須修正と推奨を明確に区別し、すべての意見が事実上のブロック命令にならないようにする必要があります。

長いルール集より安定したルールIDが先です

Cloudflareには60件を超えるRFCがあるため、毎回その全文をモデルに入れてはいません。別のエージェントがMUST・SHOULDの文をJSONに抽出し、RFC番号、タイトル、状態、ドメイン、節、要求レベル、原文リンクを付けます。レビューアーはこの圧縮された索引をまず検索し、追加の文脈が必要なときだけRFC全文を読み込みます。

各要求文には、RFCが修正された後も維持される安定したslugが付けられます。これにより、複数のシステムで同じルールの判定、分析、例外を継続して追跡できます。Cloudflareの内部AIエンジニアリングスタックも、レビュー判定で具体的なCodexルールIDを引用すると説明しています。

ルールレコードは判定文ではなく、根拠の住所です。

「API文書が不足しています」と言うより、どの文書のどの節がどの変更に適用されるかを示すことで、担当者は同じ根拠を再確認できます。ただし、Cloudflareが公開したJSONは省略された例であり、完全な外部向け設定スキーマと見なすべきではありません。

今すぐ試すこと: 非ブロッキングのルールレコードを一つ作る

Cloudflare Engineering Codexと内部レビューCLIについて、外部組織向けの公開インストール・認証手順は確認されていません。 したがって最初の実行はCloudflareツールをインストールする練習ではなく、現在のチーム文書とエディタだけで、繰り返されるレビュー意見を追跡可能なレコードに変える作業です。

  1. 準備物とアクセス権を確認します。 ブラウザで開ける現在の開発標準の正確な節へのリンク、最近のPR・MRで繰り返されたレビュー意見一つ、ルールが属するドメインと文書状態、JSONを保存する社内文書またはリポジトリを用意してください。別途Cloudflareアカウント、インストール、認証は不要です。社内原文を開く権限とレコードを保存する権限だけあれば十分です。
  2. 原文で要求レベルを確認します。 レビュー意見を該当する標準の正確な文と照合してください。必ず守るべき絶対要件か、正当な例外が可能な推奨かを、RFC 2119のMUST・SHOULDの定義で分類します。 現在有効な原文または正確な節を見つけられない場合は、自動判定候補から外してください。
  3. 次の入力を自分の文書に保存します。 これはCloudflareの公開フィールドを参考に編集部が作成したレビュー用の例であり、Cloudflareで実行される設定ファイルではありません。 
    { "rfc": "TEAM-API-001", "title": "API schema documentation", "status": "approved", "domain": "api-platform", "statements": [ { "slug": "api-schemas-must-be-documented", "section": ["API", "Schema"], "level": "MUST", "text": "外部のリクエスト・レスポンススキーマは、チームのAPI仕様に文書化しなければならない。", "href": "https://internal.example/standards/api#schema" } ]
}
  4. 原文とレコードを直接照合します。 href が正確な節を開くか、text が原文の対象を広げたり狭めたりしていないか、level が原文と一致するかを確認してください。slug は、後の判定と例外をつなげられるよう、他のルールと重ならない固定識別子として定めます。
  5. 成功状態を確認します。 状態、ドメイン、安定したslug、原文の節、要求レベル、要求文、直接リンクがすべてあり、原文と意味が一致していれば最初の結果です。status は approved のままにしてください。この段階ではPR・MRをブロックしません。

実際のブロック接続には、ルールを読む判定機、リポジトリ権限、結果形式、昇格権限、復旧経路が追加で必要です。公開資料にない観察期間や誤検知率を、Cloudflareの公式昇格基準であるかのように使ってはいけません。

ブロック前に、チェックの役割とプラットフォーム権限を分けましょう

同じ入力から常に同じ答えが得られるルールまでAIに任せる必要はありません。Cloudflareは機械的に検証可能な言語別要件にカスタムリンターを提供し、TypeScriptにはoxlintを使っています。文脈を読む必要がある違反はAIレビューアーが担い、内部CLIで同じレビューフローをローカル実行します。ただし、このCLIの外部インストールコマンドと認証方式は公開されていません。

独自の判定機をGitHubの必須ステータスチェックにつなぐ場合は、別のプラットフォームルールも適用されます。GitHub公式文書によると、マージするにはrequired checkがsuccessful、skipped、またはneutralである必要があり、ステータスを更新する想定元を特定のGitHub Appに制限できます。 これはGitLabベースのCloudflare内部実装を再現する手順ではなく、GitHubで利用できる別の実装例です。

ブロックへ昇格する前に、少なくとも誰が昇格を承認するのか、どこに判定への異議を申し立てるのか、誰が誤ったブロックを解除するのかを決めてください。AIレビューを信頼できるものにするのは、より断定的な文言ではなく、どのルールが現在は推奨で、どのルールだけがブロック権限を持つかを説明できる状態です。

さらに深く知りたいなら

How Cloudflare enforces engineering standards using AI — Codexのドメイン所有権、RFCの承認・執行分離、構造化索引、コード・仕様レビュー運用を確認できる主要事例です。 blog.cloudflare.com

RFC 2119: Key words for use in RFCs to Indicate Requirement Levels — MUSTとSHOULDの正確な意味、強い要求表現を使う基準を確認できます。 rfc-editor.org

About protected branches — GitHubで必須ステータスチェックとチェック結果の想定元を設定する際に参照できる公式文書です。 docs.github.com

The Standard of Code Review — 必須修正と軽微な意見、継続的改善と完璧主義の境界を定める際に参考になる公開原則です。 google.github.io