AIコードレビューは、ルールを増やせば強くなるのか？CodexとAGENTS.mdを形骸化させない品質保証設計

南翔伍 / AIコンパニオンとSNSの間くらいの「Jams」開発中

2026年7月22日 13:04

Codexにコードを書かせ、別のCodexにレビューさせる。

さらに、AGENTS.mdへリポジトリ固有のルールを書き、Skills、Subagents、Hooks、CI、ブランチ保護も追加する。

ここまで整えれば、かなり安全な開発環境を作れそうに見えます。

ただ、実際に運用を始めると、別の疑問が生まれます。

「ディレクトリ別のAGENTS.mdは、コードが変わるたびに古くならないか」

「ルールを詳しく書いても、Codexが必ず守るとは限らないのではないか」

「SkillsやSubagentsを増やした結果、指示同士が競合しないか」

どれも妥当な懸念です。

OpenAIが2026年7月20日に公開した「Custom Code Review rules for Codex」は、Codexのコードレビューへ、リポジトリ固有の暗黙知や設計制約を組み込む方法を紹介しています。

中核となるのは、AGENTS.mdにカスタムのコードレビュー規則を書くことです。

これによりCodex Code Reviewは、一般的なバグだけでなく、次のような「そのリポジトリを長く知る人でなければ気づきにくい問題」を検出し、根拠となる規則を示しながら指摘できます。

古いAPIやイベント名との後方互換性
顧客情報や機密情報のログ出力
他サービスが依存している名称や契約の変更
サービス間・レイヤー間の境界違反
過去の障害や設計判断に基づく禁止事項

これは有用な機能です。

一方で、私がより重要だと考えているのは、単に「AGENTS.mdへルールを書けばレビューが強くなる」という話ではありません。

自然言語のルール、再利用する工程、決定論的な検査、操作権限、マージ条件、人間の判断を分離しなければ、ルールを増やすほど品質保証の所在が分からなくなります。

この記事では、OpenAIの発表を整理したうえで、AGENTS.mdを形骸化させず、Codexを含む開発工程全体で品質を守る方法まで考えます。

AIによる実装速度が上がるほど、レビューがボトルネックになる

コーディングエージェントは、以前より大きな変更を、より長い時間をかけて実行できるようになっています。

OpenAIによれば、同社の週次プルリクエスト数は2025年第4四半期以降、2倍以上に増加しました。コード生成量が増えれば、レビュー対象も増えます。

コードを書く速度だけが上がっても、レビュー担当者が次のことを毎回調査していれば、開発全体は速くなりません。

この変更は何を目的としているのか
既存のクライアントや他サービスへ影響しないか
過去に同じ変更で事故が起きていないか
認証、データ、課金などの境界を越えていないか
例外として許可される変更なのか

しかも、問題の中にはdiffだけを見ても分からないものがあります。

例えば、レスポンスフィールドの名称変更は、コード上では自然なリファクタリングに見えるかもしれません。しかし、古いクライアントがその名称に依存していれば、変更によって利用者側が壊れます。

経験豊富なレビュアーは背景を覚えています。

しかし、新しく参加した開発者や、そのサービスを初めて扱うAIエージェントには、その歴史が見えません。

OpenAIのカスタムレビュー規則は、こうした文脈をコードの近くに置き、レビュー時に呼び出せるようにする仕組みです。

AGENTS.mdは、実装指示書からレビュー知識の入口へ広がる

Codex Code Reviewは、AGENTS.mdに記述されたリポジトリ固有の規則を読み、変更対象に関係するものをレビューへ適用できます。

重要なのは、単に「注意事項を読ませる」だけではない点です。

Codexは、検出した問題について、どのリポジトリ規則に反しているかを示しながら指摘できます。

つまり、AGENTS.mdは次の役割を持ち得ます。

実装時に守るべき行動規範
コードレビュー時の評価基準
リポジトリ固有の暗黙知への入口
過去の設計判断や事故防止策の継承手段

これまで、同じ説明がPRコメントで繰り返されていたとします。

「このフィールドは古いクライアントが使っているので削除できません」

「この値は顧客情報なのでログへ出してはいけません」

「このイベント名は他サービスが購読しています」

その説明をコードの近くへ置けば、Codexは必要な変更にだけ適用できます。

これは単なるプロンプト改善ではありません。

熟練レビュアーの記憶に依存していた品質保証知識を、リポジトリ内の共有資産へ変える仕組みと捉えた方がよいでしょう。

OpenAIの具体例が示す「実験的でも壊してはいけない契約」

OpenAIの記事では、Codexのapp-serverが送信する次の通知名が例として使われています。

rawResponseItem/completed

この通知は実験的なものとして扱われていますが、すでにCodex Cloudが利用しています。

仮に、コードを整理するため、次のように変更したとします。

- RawResponseItemCompleted => "rawResponseItem/completed"
+ RawResponseItemCompleted => "rawResponseItem/done"

変更後のコードはコンパイルできます。

しかし、既存の通知名を購読しているCodex Cloud側は、イベントを受信できなくなります。

そこで、対象リポジトリのAGENTS.mdには、次の趣旨の規則が置かれています。

## Code Review Rules

### Breaking changes

Search for breaking changes in external integration surfaces:

- raw response item events (`rawResponseItem/*`), even while experimental

この規則があれば、Codexは単に「名称変更が気になる」とコメントするのではなく、次のように具体化できます。

現在の通知名を維持する必要がある
Codex Cloudの利用側がその名称に依存している
実験的なイベントでも互換性を壊す
変更する場合は後方互換性のある経路が必要
根拠はAGENTS.mdのbreaking-change規則にある

この例で重要なのは、技術的に「公開API」と呼ばれているかどうかではありません。

現実に別のシステムが依存しているなら、それは保護すべき統合面になり得ます。

型チェックや一般的なリンターは、文字列が変更されたことは検出できても、その文字列へ別サービスが依存しているという背景までは判断できないことがあります。

だからこそ、リポジトリ固有の文脈をレビュー規則として残す価値があります。

98%対58.3%は何を意味するのか

OpenAIは、既知のルール違反と、安全な反例を含む評価スイートを使い、カスタムレビュー規則の効果を検証しました。

主要評価では、必要なカスタム指摘を回収できた割合が次のようになりました。

ルールを利用したレビュー：98%
ベースライン：58.3%

リポジトリ固有の規則を明示することで、一般的なレビューだけでは見逃される問題を大幅に拾いやすくなったことを示しています。

ただし、この数字を「Codexは98%の確率でAGENTS.mdを守る」と解釈してはいけません。

これは特定の評価スイートにおいて、必要とされたカスタム指摘をレビューが回収できた割合です。

次のものを意味する数字ではありません。

あらゆるコードベースにおける総合的なバグ検出率
Codexが実装時にルールを守る確率
本番事故を98%防げるという保証
誤検知が2%しかないという意味
人間レビューを不要にできるという意味

OpenAIも、検出率だけを評価していません。

Coverage：必要な違反を拾えるか

複雑なdiffや、複数の規則が競合する状況でも、対象となる問題を検出できるか。

Restraint：不要な指摘を抑えられるか

正常な変更、安全な例外、無関係な変更にまでルールを適用しないか。

Retention：通常のレビュー能力を維持できるか

カスタム規則へ注意が偏り、一般的なバグを見落とさないか。

Actionability：修正可能な指摘になっているか

何が、どこで、どの規則に反し、どの程度重要なのかを示せるか。

OpenAIの定義では、Actionabilityは特に、関連するガイダンス、場所、優先度が指摘に含まれるかを評価しています。

つまり、レビュー規則の品質は「違反を拾う力」だけでは決まりません。

誤検知が多く、通常のバグを見逃し、どこを直すべきか分からないなら、実務上は使いにくいでしょう。

良いルールには、検出力だけでなく、抑制力と修正可能性が必要です。

GitHub上のCodex Code Reviewは、深刻な問題へ絞って指摘する

GitHub上でCodex Code Reviewを利用する場合、PRコメントへ@codex reviewと記述してレビューを依頼できます。自動レビューを有効にし、新しいPRを毎回レビューさせることもできます。

現在の公式ドキュメントでは、GitHub上のCodexは、レビューコメントを高優先度のリスクへ集中させるため、P0とP1の問題だけを指摘すると説明されています。

これは、すべての改善点を網羅的に列挙する一般的なコード品質レビューとは少し異なります。

Codex Code Reviewの主目的は、少なくともGitHub上の標準レビューでは、次のような重大な問題を拾うことです。

本番障害につながるバグ
セキュリティやデータ境界の問題
後方互換性の破壊
重大な回帰
他サービスやモジュールへ波及する問題

命名、軽微な可読性、好みの設計、細かなリファクタリング提案まで必要なら、標準のGitHubレビューだけに期待せず、別のレビュー工程やカスタム指示を設計する必要があります。

良い規則は、重大で非自明な不変条件から始める

では、何をAGENTS.mdへ書くべきなのでしょうか。

OpenAIが推奨しているのは、重大で、非自明で、レビュアーが繰り返し説明している不変条件から始めることです。

適しているのは、例えば次のような規則です。

既存クライアントが利用するAPIフィールドを、移行期間なしに削除しない
顧客データや認証情報をログやモデルコンテキストへ送らない
課金処理では冪等性を維持する
テナント境界を越えてデータを取得しない
外部利用者が依存するイベント名を、後方互換性なしに変更しない

一方で、次のような規則は弱すぎます。

分かりやすいコードを書く
きれいな設計にする
適切にコメントする
ベストプラクティスに従う
セキュリティに配慮する

これらには、具体的な判定条件も、安全な修正経路もありません。

OpenAIは、「その規則を削除してもレビュー結果が変わらないなら、書かない方がよい」という基準を示しています。

関数名ではなく、守るべき結果を書く

次のような規則は、短期的には分かりやすく見えます。

Always call `validateUserAccessV2()`.

しかし、この関数が改名、統合、廃止されれば、ルールは古くなります。

より持続的なのは、維持すべき結果を書く方法です。

Every tenant-scoped request must verify that the authenticated user
belongs to the requested tenant before reading or modifying data.

こちらは特定の関数ではなく、「テナントデータへアクセスする前に、ユーザーの所属関係を検証する」という保証を書いています。

OpenAIも、変わりやすい関数名ではなく、互換性、データ境界、危険な副作用など、維持すべき結果を書くことを推奨しています。

ただし、結果だけを書けば十分とは限りません。

「どの経路なら安全に変更できるか」も必要です。

禁止事項と安全な変更経路をセットで書く

弱い規則は、次のようなものです。

Do not rename payment events.

これでは、新しい名称が必要になった場合にどうすべきか分かりません。

より実用的なのは、次の書き方です。

Preserve existing payment event names.

When a new name is required, emit both the old and new event names
during a documented migration period.

ここでは二つを記述しています。

不変条件：既存イベント名を維持する
安全な経路：移行期間中は旧名称と新名称を併存させる

OpenAIは、規則へ不変条件と安全な経路を含めることで、Codexが実際の違反と許容される変更を区別しやすくなると説明しています。

規則に安全な経路がなければ、Codexは問題を指摘できても、修正方法を誤る可能性があります。

ルールは、対象コードに最も近い場所へ置く

すべてのルールをルートのAGENTS.mdへ集めると、無関係な変更にも規則が適用され、ノイズが増えます。

OpenAIは、リポジトリ全体の規則はルートへ、サービス固有の規則は該当する下位ディレクトリへ置くことを推奨しています。

例えば、次のように分けられます。

repo/
├── AGENTS.md
├── frontend/
│   └── AGENTS.md
├── api/
│   └── AGENTS.md
├── database/
│   └── AGENTS.md
└── infra/
    └── AGENTS.md

ルートには、リポジトリ全体で変わりにくい原則だけを置きます。

## Repository-wide invariants

- Do not change public contracts, authentication boundaries,
  or persistent data models without explicit approval.

- Keep each change within its approved task scope.

- Run repository-defined validation before declaring completion.

- Do not claim success when required validation was skipped or failed.

下位ディレクトリには、その領域だけで重要な規則を置きます。

例えば、api/AGENTS.mdならAPI互換性、認証・認可、エラー契約。

database/AGENTS.mdならマイグレーション、データ保持、ロールバック。

infra/AGENTS.mdなら本番権限、シークレット、デプロイ経路です。

Codexは実行開始時に、グローバル設定からリポジトリルート、現在の作業ディレクトリまでの指示ファイルを順番に連結します。

より現在の作業場所に近いファイルは後から追加されるため、競合時には、より具体的な指示として扱われます。

AGENTS.mdは、実装と同じように陳腐化する

ここからが、元記事を実務へ導入する際の重要な論点です。

ディレクトリごとの実装は日々変わります。

そのため、AGENTS.mdに現在の関数名、クラス構造、ファイル一覧、細かな実装手順を大量に書けば、コードと説明はすぐに乖離します。

これは単なる更新忘れではなく、構造的な問題です。

変更頻度の高いコードと、手動更新する自然言語文書を一対一で対応させれば、どこかで同期が崩れます。

OpenAIのハーネスエンジニアリング事例でも、巨大なAGENTS.mdへ知識を集約する方法は失敗したと報告されています。

理由として、次の四つが挙げられています。

巨大な指示がタスク、コード、必要な文書のためのコンテキストを圧迫する
すべてが重要になると、実質的には何も重要でなくなる
大きなマニュアルはすぐに古いルールの墓場になる
一つの巨大な文書は、鮮度、所有者、参照関係を機械的に検証しにくい

その結果、OpenAIのチームはAGENTS.mdを百科事典ではなく、リポジトリ知識への目次・地図として扱うようになりました。

同事例では、約100行の短いAGENTS.mdを入口とし、詳細な設計、品質、信頼性、セキュリティ、実行計画などは、構造化されたdocs/配下へ分離しています。

この知見は、カスタムレビュー規則にもそのまま当てはまります。

AGENTS.mdを「現在のコードを全部説明する場所」にしてはいけません。

実務上は、次の二つの役割へ絞るのがよいと考えます。

短く、局所的な重要規則を置く
詳細な設計文書、ADR、脅威モデル、契約仕様への地図を示す

つまり、AGENTS.mdは「不変条件の短いレジストリ」であると同時に、「詳しい根拠へ移動する入口」です。

AGENTS.mdの読み込みにも上限がある

Codexは、実行開始時に指示チェーンを構築します。

CLIの対話環境では、通常、一つの起動セッションにつき一度読み込まれます。

探索順は概ね次のとおりです。

~/.codex配下のグローバルな指示
リポジトリルートの指示
現在の作業ディレクトリまでの各階層の指示
より下位の指示を後から結合

各ディレクトリでは、AGENTS.override.mdがあればそれを優先し、なければAGENTS.mdなどの候補を読みます。

また、結合されるプロジェクト指示のサイズは、デフォルトで32KiBまでです。

この仕様から、次のリスクが生じます。

ルールが多すぎると後半が読み込まれない
ルートと下位の意味的な競合が増える
作業開始ディレクトリによって指示チェーンが変わる
セッション中に更新しても、既存セッションには反映されない
重要な規則が大量の説明に埋もれる

したがって、AGENTS.md更新後の重要な実装やレビューでは、新しいセッションを開始し、読み込まれた指示元を確認する方が安全です。

サイズ上限を増やす設定もありますが、上限を広げることと、指示設計が良くなることは同じではありません。

陳腐化を防ぐには、更新をPR工程へ組み込む

AGENTS.mdへ最終更新日や所有者を書くことは有効です。

しかし、日付を更新するだけで運用した気になる危険もあります。

重要なのは、更新要否の判断を、人間の記憶へ依存させないことです。

例えば、PRで次の要素を変更した場合、AGENTS.mdや関連文書の更新要否を確認します。

API契約
DBスキーマ
認証・認可境界
個人情報の取り扱い
ログ・監査仕様
イベント名やメッセージ形式
外部サービス連携
ディレクトリの責務
ロールバック方式
既存レビュー規則が参照する設計

PRテンプレートには、次のような項目を入れられます。

## Repository guidance impact

- [ ] Existing AGENTS.md rules remain valid
- [ ] No AGENTS.md update is required
- [ ] AGENTS.md or related documentation was updated
- [ ] A natural-language rule should be migrated to CI or tests

ただし、チェックボックスだけでは形骸化します。

より有効なのは、規則とコード、テスト、所有者の対応を管理することです。

rule_id: CR-BILLING-003
applies_to:
  - services/billing/webhooks/**
related_tests:
  - tests/contracts/billing-webhooks/**
owners:
  - billing
  - security

この構造があれば、対象コードを変更した際、関連する規則、テスト、責任者を追跡しやすくなります。

OpenAIのハーネス事例でも、文書を置くだけで終わっていません。

専用のリンターとCIで、リポジトリ内の知識ベースが最新か、相互参照されているか、構造が正しいかを検査しています。さらに、古い文書を探す定期的な「doc-gardening」エージェントが、修正PRを作る運用も採用しています。

つまり、文書の保守にもハーネスが必要です。

CodexがAGENTS.mdを100%守る保証はない

ここは明確にしておく必要があります。

AGENTS.mdは自然言語のガイダンスです。

Codexの判断を改善しますが、決定論的な制約ではありません。

次のような失敗は起こり得ます。

ルールの読み落とし
ルールの誤解
複数ルール間の競合
例外条件の誤認
関連規則の適用漏れ
長いコンテキスト内での注意力低下
問題を検出しても修正方法を誤る
実装者による自己レビューで判断を追認する

OpenAIも、Codex Code Reviewを追加のレビュアーと位置づけています。

テスト、ブランチ保護、必須承認などの強制機構を置き換えるものではありません。

この限界は、実際の導入事例からも読み取れます。

Datadogは、過去のインシデントにつながったPRを再検証し、Codexが10件超、調査対象の約22%について、当時提示されていれば違いを生んだとエンジニアが判断する指摘を出したと報告しています。

一方で、この22%は「すべての本番障害の22%を防げる」という一般的な数値ではありません。

Datadogが選んだ過去のインシデントとPRを対象にした再生評価であり、同社のエンジニアが指摘の有用性を判断した結果です。

OpenAIとDatadog自身も、この結果を人間の判断の代替ではなく、人間が見落としたシステム横断リスクを補完したものとして説明しています。

重要な制約をAGENTS.mdだけへ置くのは危険です。

重要度に応じて、ガイダンスと強制を分離する

品質保証を安定させるには、ルールの性質に応じて、異なる機構へ責務を分けます。

AGENTS.md：永続的な不変条件とレビュー観点

置くのは、次のような非自明な設計制約です。

後方互換性を維持すべき統合面
データ、認証、テナントの境界
過去の事故から得た禁止事項
例外を認める条件
安全な変更経路
詳細な設計文書への入口

詳細な作業手順、頻繁に変わる実装名、機械的に検査できる形式規約は避けます。

Skills：再利用するワークフロー

OpenAIは、繰り返し行う作業を、長いプロンプトや毎回のやり取りへ依存させず、Skillとしてまとめることを推奨しています。

例えば、次のような工程です。

Planレビュー
DBマイグレーション確認
UIのスクリーンショット検証
セキュリティレビュー
diffレビュー
Goal監査
リリース前確認

AGENTS.mdは「常に意識する不変条件」、Skillは「特定の目的で実行する手順」と分けると、責務が明確になります。

ただし、Skillも自然言語とモデル判断を含むため、重要な検査を必ず成功させる強制機構ではありません。

Subagents：探索・検査・レビューの役割分離

Subagentsは、複数の専門的な観点を、別のコンテキストで並行処理する用途に向いています。

例えば、次のように分けられます。

セキュリティの問題を探すエージェント
テスト不足を探すエージェント
API互換性を見るエージェント
保守性と責務境界を見るエージェント

役割を分けることで、一つの長いセッションが自分の実装を追認する危険を減らせます。

ただし、Subagentもレビュアーであり、強制機構ではありません。

複数のAIが同じ誤った前提を共有する可能性もあります。

テスト・リンター・CI：決定論的に確認できる品質ゲート

次のような検査は、自然言語ルールだけに頼るべきではありません。

lint
フォーマット
型チェック
単体・統合・契約テスト
スキーマ検証
API互換性検査
マイグレーション整合性
シークレットスキャン
禁止依存の検出
ビルド成功

OpenAIも、フォーマット、lintなどの機械的な検査をレビュー規則へ書かず、CIに残すよう明記しています。

Codex Rules・Sandbox・IAM：危険な操作の制御

Codex Rulesは、Codexがサンドボックス外で実行するコマンドを制御する仕組みです。

コマンドのプレフィックスに応じて、次の判断を設定できます。

allow：許可
prompt：実行前に確認
forbidden：禁止

複数の規則が一致した場合は、forbidden、prompt、allowの順で、最も厳しい判断が適用されます。

Rulesは現時点で実験的な機能であり、変更される可能性があります。

適しているのは、例えば次のような操作制御です。

本番DBへの直接変更
危険な削除コマンド
承認なしのデプロイ
シークレットへのアクセス
権限変更
外部サービスへの書き込み

ただし、Codex Rulesは主にコマンド実行の権限制御です。

API互換性やコード品質を判断するレビュー規則とは、役割が異なります。

また、本当に危険な操作は、Codex側の設定だけでなく、クラウドIAM、データベース権限、デプロイ環境、GitHub権限でも制限する必要があります。

ブランチ保護・必須チェック：マージ可否の強制

絶対に守る必要がある条件は、Codexの判断外で強制します。

必須テストが失敗している
API互換性検査が失敗している
マイグレーション検査が失敗している
セキュリティ検査が失敗している
CODEOWNERSの承認がない
高リスク変更の人間承認がない

これらは、GitHub Actions、required status checks、branch protection、CODEOWNERSなどでマージ不能にします。

人間承認：目的、例外、責任

最後まで人間が保持すべきなのは、次のような判断です。

この変更は本当に必要か
製品の目的や顧客価値に合っているか
許容するリスクはどこまでか
例外を認めるべきか
本番へ出すか、止めるか
問題が起きたとき誰が責任を持つか

人間がすべてのコードを手作業で読む必要はありません。

しかし、目的、採否、例外、停止、責任までAIへ曖昧に委ねるべきではありません。

同じ規則を、すべての機構へ重複させない

AGENTS.md、Skills、Subagents、Rules、CIを使えるようになると、同じ規則を全部へ書きたくなります。

これは避けた方がよいでしょう。

同じ内容が複数の場所にあると、どれが正式なのか分からなくなります。

片方だけ更新され、別の場所には古い規則が残ります。

さらに、自然言語上のわずかな表現差から、意味がずれることもあります。

推奨する責務分離は、次のとおりです。

AGENTS.md：永続的な不変条件、境界、レビュー観点、詳細文書への入口
Skill：明示的に実行する再利用ワークフロー
Subagent：独立した専門分析・レビュー
Rule・Sandbox・IAM：操作権限の許可、確認、禁止
CI：機械検証できる品質ゲート
Branch protection：マージ条件
人間：高リスク判断、例外、目的適合性、責任

この分離ができれば、「問題が起きたので、とりあえずAGENTS.mdへ追記する」という運用を避けられます。

自然言語のレビュー規則にもテストが必要になる

カスタムレビュー規則の導入で、最も重要なのは文章を書くことではありません。

そのルールが、期待どおりに機能するかを評価することです。

OpenAIは、代表的な変更で最低でも次の3種類を試すよう勧めています。

指摘すべき違反
許容すべき安全な変更
規則と無関係な変更

例えば、「既存の課金イベント名を移行期間なしに変更しない」という規則なら、次のケースを用意します。

Positive：指摘すべき違反

既存イベント名を削除し、新しい名称だけを送信する変更。

Negative：安全な変更

旧名称を維持しながら、新しい名称を追加する変更。

Unrelated：無関係な変更

イベント契約とは関係のない管理画面の文言修正。

評価するのは、次の項目です。

Detection：違反を検出したか
Restraint：安全な変更を誤検知しなかったか
Scope：無関係な変更へ反応しなかったか
Actionability：問題の場所、根拠、優先度を示したか
Retention：通常のバグレビュー能力を維持したか
Freshness：現在の設計と整合しているか

この評価をせずにルールを増やせば、検出効果よりも誤検知や保守負担が大きくなる可能性があります。

成熟したルールは、テストやCIへ移す

レビュー規則を、永遠にAGENTS.mdへ残す必要はありません。

例えば、最初は次の自然言語ルールが必要だったとします。

Do not remove existing billing webhook fields without a migration path.

運用を続けるうちに、既存フィールド一覧と変更後スキーマを比較する契約テストを作れるようになったとします。

その時点で、互換性の主要部分はCIで決定論的に検査できます。

そうなれば、AGENTS.mdには長い説明を残さず、次のように縮小できます。

Run the billing contract tests after changing webhook schemas.
Do not bypass failures without billing-owner approval.

自然言語規則には、次の成熟経路があります。

人間の暗黙知
↓
AGENTS.mdのレビュー規則
↓
違反例・安全例・無関係例で評価
↓
検査方法を標準化
↓
テスト・リンター・CIへ移行
↓
AGENTS.mdを縮小または削除

良い運用とは、AGENTS.mdの項目が増え続ける運用ではありません。

曖昧だった知識が、徐々にコード、型、テスト、CIへ昇格していく運用です。

ルールには、追加条件だけでなく削除条件も必要

レビュー規則へ次の情報を持たせると、形骸化を防ぎやすくなります。

### CR-AUTH-001: Tenant boundary

対象:
- `services/api/tenant/**`

不変条件:
- テナントデータを読む前に、
  認証ユーザーと対象テナントの関係を検証する。

安全な経路:
- 共通認可レイヤーを利用する。
- 例外実装にはsecurity ownerの承認と専用テストを必要とする。

根拠:
- 複数テナント間のデータ漏えい防止。

所有者:
- Security / API owner

廃止条件:
- 認可がデータアクセス層で構造的に強制され、
  個別実装で回避できなくなった場合。

特に重要なのは、廃止条件です。

「認可が構造的に強制され、個別実装で回避できなくなったら削除する」と決めておけば、古い注意書きを残し続けずに済みます。

ルール数が20、30と増えてきた場合は、次のいずれかを疑うべきです。

本来CIへ移すべき規則が残っている
ディレクトリの責務が広すぎる
アーキテクチャが複雑すぎる
実装詳細をルールへ書いている
重複した規則が存在する
コード構造で強制できる制約を文章で補っている

ルールの増加は、品質向上の証拠とは限りません。

設計負債の兆候である可能性もあります。

Codex・Claude Codeの開発工程では、diffレビューの評価基準として使う

私は、CodexやClaude Codeを使う開発では、全工程を一つのAI、一つの長いセッションへ任せるより、工程を分けた方が安定すると考えています。

例えば、次の流れです。

上流設計
→ 探索
→ 局所Plan
→ Planレビュー
→ 実装・自動検証
→ diffレビュー
→ Goal監査
→ 人間承認

この中で、カスタムレビュー規則が最も直接的に機能するのは、diffレビュー工程です。

実装を行ったセッションとは別のCodexに、変更差分とリポジトリ固有の不変条件を照合させます。

例えば、最初は次のような規則が候補になります。

公開API、DBスキーマ、認証境界を無断で変更しない
既存ユーザーのデータ形式を後方互換性なしに変更しない
個人情報、認証情報、顧客データをログへ出さない
承認されたスコープ外のリファクタリングを混ぜない
受入条件を満たしていない状態で完了と判定しない
ロールバック不能な破壊的変更を無断で行わない

ただし、AGENTS.mdへ上流要件の全文を書くわけではありません。

役割を次のように分けます。

Goal・スコープ・受入条件：仕様書や設計書
タスク固有の変更手順：局所Plan
永続的な不変条件：AGENTS.md
再利用するレビュー工程：Skill
機械的な検査：テスト・CI
変更全体の目的適合性：Goal監査
リリース判断：人間承認

OpenAIのハーネスエンジニアリング事例でも、大きな目標を小さな作業単位へ分け、ローカルレビュー、専門エージェントのレビュー、人間とエージェントからのフィードバックを反復する工程が採用されています。

同時に、巨大なAGENTS.mdへすべてを集約せず、構造化された知識、テスト、CI、文書検査へ責務を分けています。

複数のAIを使うこと自体が品質を保証するわけではありません。

しかし、実装とレビューの役割を分け、異なる証拠と評価基準を持たせることで、一つの長いセッションが自分の判断を追認する危険は減らせます。

最初は、最重要ルールを3個だけ導入する

最初から大規模なルール体系を作る必要はありません。

OpenAIも、まず2〜3個の簡潔な規則から始めるよう推奨しています。

1. 最重要ルールを3個だけ選ぶ

選定条件は次の三つです。

見逃した場合の影響が大きい
コードだけでは自明ではない
レビューで同じ説明が繰り返されている

2. 各ルールに3ケースを用意する

指摘すべき違反
許容すべき安全な変更
完全に無関係な変更

3. 対象コードに最も近いAGENTS.mdへ置く

無関係な変更へ広く適用しないことが重要です。

4. 独立したレビュー工程で試す

実装を行ったセッションとは別のCodexでレビューします。

5. 結果を記録する

違反を拾えたか
誤検知したか
無関係な変更へ反応したか
根拠と優先度を示したか
通常のバグを見落とさなかったか

6. 機械化できるものをCIへ移す

ルールを蓄積するのではなく、成熟させます。

最も避けるべきなのは「指示を増やせば守る」という発想

AIが間違えたとき、私たちは指示を追加したくなります。

「この場合は禁止」

「このディレクトリでは必須」

「このSkillを必ず使う」

「レビューではこの項目も確認する」

一つひとつは妥当に見えます。

しかし、追加を続けると次の問題が起きます。

コンテキストが圧迫される
適用範囲が曖昧になる
指示が競合する
古い規則が残る
誤検知が増える
重要なルールが埋もれる
どの機構が品質を保証するのか分からなくなる

OpenAI自身のハーネス事例でも、巨大なAGENTS.mdは、古い規則の墓場になり、検証困難になったと報告されています。

問題は、Codexへ読ませる文章量が足りないことではありません。

曖昧な判断、再利用する工程、決定論的な検査、危険操作、マージ条件が、同じ自然言語レイヤーへ混在していることです。

まとめ：ルールを増やすのではなく、品質保証の階層を作る

OpenAIのカスタムコードレビュー規則は、有用な機能です。

過去の事故、設計意図、互換性、データ境界といった暗黙知を、コードの近くに置き、Codexが根拠付きでレビューできるようになります。

一方で、AGENTS.mdは万能な強制機構ではありません。

コードの変化によって古くなり、規則同士が競合し、モデルが読み落とす可能性もあります。

最終的な推奨方針は、次です。

AGENTS.mdは少数の永続的な不変条件と、詳細な知識への地図に限定する。再利用工程はSkills、独立分析はSubagents、決定論的検査はテスト・CI、危険操作はRules・Sandbox・IAM、マージ可否はブランチ保護、人間は目的・例外・責任を保持する。

そして、重要なレビュー規則には、違反例、安全例、無関係例を用意します。

機械化できた規則は、テスト、リンター、CIへ移し、AGENTS.mdから縮小または削除します。

AIコードレビューの品質を決めるのは、ルールの数ではありません。

暗黙知をどこへ記録し、何をAIへ判断させ、何を機械的に強制し、どこで人間が責任を持つか。

その全体設計です。

「AIに同じ指示を繰り返していないか？組織の知識を『仕組み』に変える方法」
- 繰り返す修正を、ルール、Skill、テスト、評価基準へ変換する考え方を整理しています。
「AIエージェントの性能は、なぜモデルだけで決まらないのか？安全に動かすハーネス設計の10要素」
- 権限、状態、検証、ログ、停止、復旧を含めた実行基盤の全体像を解説しています。
「Codex・Claude Codeに全部任せると、なぜ開発は迷走するのか？AI開発を安定させる工程設計」
- 要件、Plan、実装、検証、レビュー、Goal監査を分離する開発工程を具体化しています。

企業で実行する場合

この記事で扱った考え方を、自社リポジトリのAGENTS.md設計、Codex・Claude Codeの開発工程、レビューSkill、CI、権限、評価運用へ落とし込みたい場合は、研修、業務設計、開発、改善運用までの支援内容を仕事依頼記事にまとめています。

出典・参考資料

OpenAI Developers「Custom Code Review rules for Codex」2026年7月20日
OpenAI Codex documentation「Custom instructions with AGENTS.md」
OpenAI Codex documentation「Codex code review in GitHub」
OpenAI Codex documentation「Best practices」
OpenAI Codex documentation「Rules」
OpenAI「Harness engineering: leveraging Codex in an agent-first world」2026年2月11日
OpenAI「Datadog uses Codex for system-level code review」2026年1月9日

いいなと思ったら応援しよう！

社会問題×マーケティングが好き / ㍿小さな一歩（前澤ファンド出資先）で養育費の未払い問題にビジネスでトライ→㍿SHIRO創業。社会問題の発見→要因分析→ビジネス考案→実行に必要な資本整備→実行・改善のサイクルが最短で回り社会問題が解決されつづけるインフラを創る。