社内の開発ルールをAIに読ませるだけでは、標準は執行されません。文書を「推奨」と「ブロック」の状態に分け、各ルールに追跡可能なIDを付けて初めて、AIレビューは個人の意見ではなく運用システムになります。
Cloudflareが作ったのはAIレビュアーというより「ルールの台帳」です
Cloudflareは2026年8月に公開した事例で、AIコードレビュアーが4か月間に約25万件のエンジニアリング標準違反を指摘し、1万6千件のマージを防いだと明らかにしました。同じ標準を使う仕様レビュアーは、実装前の技術設計を約600件レビューしました。 規模は目を引きますが、より重要なのはどのモデルを使ったかではありません。人と複数のエージェントが共通して参照する単一のルール台帳を先に作った点です。
以前は、公式文書、リポジトリのファイル、チャット履歴、担当者の記憶にガイダンスが散らばっていました。見つけた内容が最新か、権威あるものか、現在の作業に適用されるかを判断するのも難しかったのです。Cloudflareはこれを「Engineering Codex」という管理された標準リポジトリに移しました。アーキテクチャ、セキュリティ、信頼性、TypeScript、Rustなどのドメインごとにオーナーを置き、従業員がマージリクエストでRFCを提案すると、複数段階のレビューを経てオーナーが最終承認する仕組みです。
標準の文言にはRFC 2119の MUST と SHOULD を使います。RFC 2119では、MUSTは絶対的な要件であり、SHOULDは妥当な事情がある場合に影響を十分検討したうえで逸脱できる推奨です。この文書は、こうした強い表現を相互運用性や危害の防止に本当に必要な場合に慎重に使うよう求めています。 つまり、すべてのベストプラクティスをMUSTへ引き上げても標準が強くなるわけではなく、ブロック理由が乱用されて信頼を失いやすくなります。
良いルールには、答えだけでなく適用条件も含まれます。
「OpenAPIを書く」よりも、「外部に公開されるリクエスト・レスポンススキーマはOpenAPIで文書化しなければならない」の方が機械的に判定しやすくなります。適用対象、要件レベル、根拠、例外の承認者、原文リンクを一組で管理してみてください。
要点は、承認と執行を分ける二つのスイッチです
CloudflareのRFCは、承認されたからといって直ちにマージをブロックしません。approved 状態では違反を非ブロッキングの推奨として示し、別途昇格して enforced になって初めてMUST違反をブロックします。チームが新しいルールを受け入れる時間と、自動判定の正確性を確かめる時間を別々に確保する構造です。
| 状態 | レビューの動作 | 確認する運用指標 |
|---|---|---|
| ドラフト | オーナーと関係者が文言・範囲をレビュー | 曖昧な条件、重複ルール、例外経路 |
| 承認済み | AIは推奨するがマージは許可 | 誤検知率、修正受容率、繰り返される質問 |
| 執行中 | 検証済みのMUST違反だけをブロック | ブロック解除時間、例外率、回避の試み |
| 廃止 | 新規判定を停止し、履歴は保持 | 代替ルールへのリンク、既存例外の整理 |
この方法は、コードホスティングプラットフォームの実際の執行機構にもよく合います。GitHubの保護ブランチでは、必須ステータスチェックが成功・スキップ・ニュートラルのいずれかでなければマージできず、特定のGitHub Appが作成したチェック結果だけを信頼するよう出所を制限することもできます。 AIレビュー結果をブロッキングゲートにつなぐなら、「誰がどの権限で成功状態を記録できるのか」までルール設計に含める必要があります。
一方で、SHOULDや個人の好みまでブロックするとレビューは遅くなります。Googleの公開コードレビューガイドも、完璧なコードを求めるより、変更がコードベース全体の健全性を明確に改善するなら承認することを勧めています。スタイルは文書化されたスタイルガイドを権威とし、細かな意見は必須ではないことを明示するよう求めています。 AIも同じです。根拠のある必須修正、推奨、参考意見を画面上で明確に区別しなければ、開発者はすべての文をブロック命令だと誤解してしまいます。
25万件の検知が、そのまま25万件の品質改善を意味するわけではありません。
Cloudflareが公開した数値は自社運用の集計であり、独立評価の結果ではありません。同じ違反の繰り返し、誤検知、開発者が受け入れた割合は別途示されていません。検知件数だけでなく、ルール別の受容率・例外率・ブロック解除時間・再発率を合わせて見るべきです。
長い文書を丸ごと入れず、「探索用インデックス」と原文を分けましょう
Cloudflare Codexにはすでに60件を超えるRFCがあり、毎回すべての全文書をモデルのコンテキストに入れるのは困難です。そのため別のエージェントがMUST・SHOULDの文をJSONに抽出し、RFC番号、ドメイン、状態、セクション、原文リンクなどのメタデータを付けます。レビュアーはまずこの圧縮インデックスを検索し、判断に追加の文脈が必要なときだけRFC全文を読み込みます。
各文には、RFCが改訂されても維持される安定したslugが付与されます。このIDがあれば、同じルールの検知量と誤検知を期間ごとに比較し、例外の承認・廃止履歴を結び付けられます。AIが「セキュリティ上よくありません」とだけ言えば意見ですが、「SEC-API-014違反であり、根拠は原文3.2節」と記録すれば、再現して異議を申し立てられる判定になります。
ルールと執行コードを分離する考え方は、AIだけのものではありません。Open Policy Agentは、ポリシーを宣言的なコードで書き、アプリケーションが構造化されたJSON入力を送って判定を得るよう設計されています。ポリシー決定と実際の執行を分離し、CI/CD、APIゲートウェイ、Kubernetesなどで利用できます。 確実に機械判定できる項目はリンターやポリシーエンジンに任せ、文脈判断が必要なアーキテクチャと文書品質だけをAIに残す方が、速く監査もしやすくなります。
Cloudflareも同じ階層を選びました。機械的に検証できる言語ルールはカスタムリンターでミリ秒単位に表示し、AIレビュアーは関連RFCを見つけて、文脈上の違反かどうかを評価します。また、CI前にローカルCLIで同じレビューを実行できるようにして、フィードバックまでの距離も縮めました。 自社のAIエンジニアリングスタックでは、すべての標準CIリポジトリのマージリクエストをAIがレビューし、判定ごとに具体的なCodexルールIDを引用すると説明しています。
今週、小さなリポジトリ一つで始める4ステップ
繰り返されるレビューコメントを10件だけ集めましょう
直近のPRまたはMRを30件見て、2回以上繰り返されたコメントを選びます。各項目に rule_id、適用パス、要件レベル、根拠リンク、オーナー、例外承認者を記載してください。「きれいに書く」のように判定条件のない文は除外します。
リンターとAIの境界を先に分けましょう
AST・正規表現・スキーマで確実に捉えられるルールは、ESLint、oxlint、Semgrep、OPAなどの決定論的検査に送ります。設計意図や文書の文脈を読む必要があるルールだけをAIキューに残してください。同じ違反を二つのツールが重複して報告しないよう、代表する検査器を一つ指定します。
2週間、警告モードで観察しましょう
AIの結果にはルールID、重要度、根拠、問題の位置、確信度、原文リンクを出力しますが、マージはブロックしません。開発者が「受容・誤検知・例外申請」のいずれかを選べるようにし、ルール別の受容率を記録してください。標本が少ない場合は、期間だけでなく最小判定件数を基準にします。
検証済みのMUSTだけを必須チェックへ昇格させましょう
セキュリティ、データ損失、互換性のように違反コストが高く、誤検知が十分に低い項目だけを、ブランチ保護の必須ステータスチェックにつなげます。例外には有効期限と承認者を求め、ブロック解除時間や例外率が急増したら自動で警告モードに戻す運用条件も定めてください。
最終承認の責任は、ルールオーナーとコードオーナーに残してください。AIは作業の瞬間に関連ガイダンスを見つける執行インターフェースであり、どのルールが組織にとって正しいかを自ら決める権威ではありません。
さらに深掘りしたい場合
How Cloudflare enforces engineering standards using AI — CodexのRFCライフサイクル、JSONインデックス、コード・仕様・インシデント報告書のレビュー構成を説明する中核事例です。 blog.cloudflare.com
The AI engineering stack we built internally — on the platform we ship — リポジトリの文脈、マルチエージェントレビュー、Codexが実際の開発スタックでつながる仕組みを確認できます。 blog.cloudflare.com
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels — MUST・SHOULD・MAYの正確な意味と、強い要件表現を使う基準を確認できます。 rfc-editor.org
About protected branches — 必須ステータスチェック、承認、会話の解決、マージキューを実際のリポジトリゲートとして設定する際に参照できる公式文書です。 docs.github.com
Open Policy Agent (OPA) — 構造化入力と宣言的ポリシーを分離し、CI/CDとインフラで執行するポリシーコードのアプローチを紹介します。 openpolicyagent.org
The Standard of Code Review — ブロックすべき品質問題と、完璧主義・個人の好みを区別するコードレビュー原則を整理した資料です。 google.github.io
