Codexで使うAGENTS.mdの書き方｜チーム開発ルールをAIに伝える設計ガイド

本記事を読めば、AGENTS.mdで開発ルールやレビュー基準をCodexに伝えられるようになり、チーム内のAI出力品質を安定化できます。

Codexは作業前に指示ファイルを参照できますが、書き方が曖昧だと確認漏れや不要な差分が発生します。AIzen株式会社は、AI開発支援と業務システム開発の現場で、AIに任せる作業と人が確認する判断を分ける運用設計を支援しています。

本記事では、AGENTS.mdの役割、優先順位、書くべき項目、チーム運用までを整理します。

AGENTS.mdとは

AGENTS.mdは、Codexに対してリポジトリの作業ルールを伝えるためのMarkdownファイルです。READMEが人間向けの説明を担うのに対し、AGENTS.mdはCodexが作業前に参照する実務ルールとして使います。

重要なのは、AGENTS.mdを「AIへのお願い集」にしないことです。開発者が普段レビューで確認している基準、テスト実行の条件、触ってよい範囲、承認が必要な操作を、Codexが迷わず実行できる粒度で書く必要があります。

Codexに伝える開発ルール

AGENTS.mdに書くべき中心は、リポジトリ固有の開発ルールです。たとえば「パッケージ管理はpnpmを使う」「APIレスポンス形式を変える場合は互換性を確認する」「UI変更後は対象画面をブラウザで確認する」といった、プロジェクトごとの前提を明文化します。

Codexは一般的な開発知識を持っていますが、社内の命名規則、ディレクトリ責務、レビュー文化までは自動で把握できません。チームが暗黙知として扱っている判断基準をAGENTS.mdに移すことで、AIが作る差分をレビューしやすくなります。

レビュー基準とテスト方針

AGENTS.mdには、レビュー時に見てほしい観点と、変更後に実行すべきテストを書きます。単に「テストする」と書くのではなく、「TypeScript変更時は型チェック」「UI変更時は対象画面のスクリーンショット確認」「DBスキーマ変更時はマイグレーション差分を説明」といった条件付きの指示にします。

レビュー基準は、セキュリティ、回帰、パフォーマンス、アクセシビリティ、ログ出力、例外処理のようにカテゴリ化すると運用しやすいです。Codexに毎回同じ観点で確認させることで、レビュー担当者は高リスク箇所の判断に集中できます。

READMEとの役割の違い

READMEとAGENTS.mdは役割を分けて管理します。READMEは新規参加者や利用者が読む説明書で、セットアップ方法、機能概要、運用手順を載せます。AGENTS.mdはCodexが作業時に参照する指示書で、編集ルール、確認コマンド、禁止操作、レビュー観点を載せます。

ファイル	主な読者	書く内容	更新タイミング
README.md	開発者・利用者	概要、起動方法、利用手順	機能や導入方法が変わったとき
AGENTS.md	Codex・AI開発担当	編集ルール、テスト、レビュー基準	AIに任せる作業範囲が変わったとき
config.toml	Codex実行環境	サンドボックス、MCP、モデル設定	実行環境や権限方針が変わったとき

「READMEに全部書けばよい」と考えると、人間向け説明とAI向け制約が混ざります。AGENTS.mdは、Codexが差分を作る直前に必要な実務ルールへ絞るのが基本です。

AGENTS.mdの優先順位

Codexの公式情報では、AGENTS.mdはグローバル、プロジェクト、現在の作業ディレクトリに近い順で読み込まれ、近い場所の指示が後から効く形で扱われます。チームで使う場合は、この優先順位を前提にファイル配置を設計します。

優先順位を理解しないまま複数のAGENTS.mdを置くと、意図しない指示が残ったり、特定ディレクトリのルールが反映されなかったりします。まずは共通ルールを上位に置き、専門領域の指示だけを下位に分けると整理しやすいです。

グローバル指示の使いどころ

グローバル指示は、個人のCodex環境全体に適用したい作業方針に向いています。たとえば「既存変更を勝手に戻さない」「不明な仕様は断定せず確認する」「日本語で簡潔に報告する」といった、どのリポジトリでも共通する働き方を書きます。

一方で、特定プロジェクトのコマンドやディレクトリ構造をグローバルに書くのは避けるべきです。別リポジトリで誤ったコマンドを実行する原因になります。グローバルには人格・作業姿勢・共通安全ルール、プロジェクトには実装ルールを置く分担が安全です。

プロジェクト指示の上書き範囲

プロジェクト直下のAGENTS.mdには、そのリポジトリ全体に効くルールを書きます。セットアップ、テスト、Lint、PR前確認、主要ディレクトリの説明、外部サービスの扱いなど、開発者全員が共有すべき内容です。

Codexは作業開始時に指示を読みます。変更したAGENTS.mdがすでに進行中のセッションへ即時反映されるとは限らないため、重要な変更後は新しいセッションや新しい作業単位で確認します。プロジェクト指示は短く保ち、常に実行可能な内容にすることが品質安定の前提です。

ディレクトリ単位で分ける基準

フロントエンド、API、バッチ、インフラのようにルールが大きく違う場合は、ディレクトリ単位でAGENTS.mdを分けます。たとえば apps/web/AGENTS.md にはUI確認やアクセシビリティ、services/api/AGENTS.md には認証、DB、ログ出力のルールを書く形です。

分ける基準は「同じ変更でも確認コマンドやレビュー観点が変わるか」です。単にチーム名ごとに分けるのではなく、Codexが作業時に参照すべき実務差分があるかで判断します。細かく分けすぎると管理負荷が増えるため、最初はリポジトリ直下と主要ディレクトリ数個に絞ると運用しやすいです。

AGENTS.mdの書き方

AGENTS.mdは長文の理念より、Codexが作業に移せる具体的な指示を優先します。見出しは「作業前確認」「編集ルール」「テスト」「レビュー観点」「禁止操作」のように、実際の作業順に並べると読みやすくなります。

AIzenの開発支援でも、最初から完璧な指示書を作るより、既存のPRレビューコメントや不具合対応履歴から頻出項目を抽出し、少しずつAGENTS.mdへ反映する進め方を推奨しています。

作業前確認と編集ルール

作業前確認では、Codexに最初に見てほしい情報を書きます。たとえば「作業前に関連するREADMEと既存実装を確認する」「既存の命名規則に合わせる」「不要なリファクタリングをしない」「生成物やロックファイルを不用意に変えない」といった項目です。

編集ルールは、禁止だけでなく許可範囲も書くと効果的です。「このディレクトリ内のコンポーネント変更は許可」「共通APIのシグネチャ変更は事前説明が必要」のように境界を明確にすると、Codexの差分が過剰に広がりにくくなります。

テスト実行とレビュー観点

テスト指示は、変更対象に応じて分けます。すべての変更で重いE2Eを必須にすると運用が止まりやすいため、軽微な文言修正、UI変更、API変更、DB変更のように段階を分けます。

変更内容	Codexに指示する確認	人が見るポイント
文言・ドキュメント	表記ゆれ、リンク、見出し維持	事実関係、ブランド表現
UI変更	対象画面の表示、主要操作	デザイン意図、ユーザー影響
API変更	型チェック、関連テスト	互換性、認証、エラー処理
DB変更	マイグレーション、ロールバック観点	本番影響、データ移行

レビュー観点は、PRテンプレートや過去のレビューコメントから抽出すると現場に合います。「認証情報をログに出さない」「日付処理はタイムゾーンを確認する」など、過去に起きた問題ほどAGENTS.mdに書く価値があります。

禁止操作と承認条件

禁止操作は、抽象的な「危険なことをしない」ではなく、具体的な行為で書きます。例として、本番データ削除、秘密情報の表示、外部送信、依存関係の大幅更新、マイグレーションの書き換え、既存変更の巻き戻しなどがあります。

ただし、AGENTS.mdだけで実行を完全に制御できるわけではありません。安全性はサンドボックス設定、承認ポリシー、MCPや外部ツールの権限と合わせて設計します。AGENTS.mdには「どの操作は人の承認が必要か」を書き、実際の実行環境側でも権限を絞るのが現実的です。

チーム開発でのAGENTS.md運用ルール

AGENTS.mdは作成して終わりではありません。開発ルールやレビュー基準が変われば、指示ファイルも更新する必要があります。チーム運用では、誰が更新し、誰がレビューし、どのタイミングで廃止するかを決めます。

特にAI活用が進むと、各メンバーが便利な指示を追加しがちです。増えた指示をそのまま残すと、Codexが重要な条件を見つけにくくなります。短く、具体的で、現行運用に合う状態を保つことが重要です。

長すぎる指示の整理

長すぎるAGENTS.mdは、読み手にもCodexにも扱いづらくなります。公式情報でも、プロジェクト指示には読み込み上限があるため、重要な指示ほど上部へ置き、詳細説明はREADMEやdocsへ逃がす設計が向いています。

整理するときは、指示を「必須」「条件付き」「参考」に分けます。必須はAGENTS.mdへ残し、条件付きは対象ディレクトリのAGENTS.mdへ分け、参考情報はドキュメントへ移します。AGENTS.mdは行動を変える指示だけに絞ると、更新しやすくなります。

変更履歴とレビュー担当の管理

AGENTS.mdの変更は、通常のコード変更と同じようにレビュー対象にします。なぜなら、AIの作業結果に直接影響するからです。テストコマンドを変える、禁止操作を追加する、対象ディレクトリのルールを変える場合は、開発リーダーやレビュー担当が確認します。

変更履歴には「何を追加したか」だけでなく「なぜ追加したか」を残します。過去の不具合、レビュー漏れ、手戻りの再発防止として追加した指示は、理由がわかると将来の整理時に残すべきか判断しやすくなります。

レビュー基準の書き漏れ防止

レビュー基準の書き漏れを防ぐには、PRレビューで出た指摘を定期的にAGENTS.mdへ反映する運用が有効です。毎月またはリリースごとに、指摘が多かった観点を確認し、AIにも事前確認させたいものを追加します。

弊社エンジニアからのコメント：

AGENTS.mdは、最初から長い社内規程を貼るより、直近3か月のPRレビューで繰り返し出た指摘を10項目ほど入れるほうが効果を出しやすいです。特に「テスト未実行」「既存変更の巻き戻し」「認証まわりの確認漏れ」は、AIに事前確認させるだけでレビュー時間を短縮しやすくなります。

AGENTS.mdを社内AI運用に展開する方法

AGENTS.mdはCodex専用の設定ファイルとしてだけでなく、社内のAI開発ルールを整理する入口にもなります。AIに任せる作業、任せない判断、人が承認する操作を言語化することで、他のAIツール運用にも転用しやすくなります。

社内展開では、個人の便利設定を集めるだけでなく、部署やプロジェクトごとの責任範囲に合わせて共通ルールを作ることが重要です。AIzenでは、開発支援だけでなく、AI利用ガイドラインやレビュー体制の整備まで含めて設計します。

プロンプト資産の管理方法

AGENTS.mdに書いた内容は、プロンプト資産として管理できます。作業依頼テンプレート、レビュー観点、テスト条件、禁止操作を分けて蓄積すれば、Codex以外のAI開発ツールや社内チャットボットにも応用できます。

ただし、すべてをAGENTS.mdに集約する必要はありません。共通の考え方は社内ガイドラインへ、リポジトリ固有の実行ルールはAGENTS.mdへ、繰り返し使う作業手順はSkillsへ分けると、管理対象が整理されます。

プロジェクト横断の共通ルール

複数プロジェクトでCodexを使う場合は、共通ルールと個別ルールを分けます。共通ルールには、秘密情報の扱い、外部通信、承認条件、レビュー報告の形式を置きます。個別ルールには、技術スタック、テストコマンド、ディレクトリ構成を置きます。

この分担により、新しいプロジェクトへCodexを導入するときも、ゼロからルールを作らずに済みます。開発マネージャーは共通ルールを維持し、各プロジェクト担当者は固有ルールだけを更新する運用にできます。

社内運用設計に相談する範囲

社内運用設計で相談すべき範囲は、AGENTS.mdの文面だけではありません。AIに渡してよい情報、操作権限、レビュー担当、承認フロー、監査ログ、教育資料まで含めて整理する必要があります。

AIzen株式会社では、既存リポジトリの確認、AGENTS.mdの初期設計、PRレビュー基準の整理、Codex導入後の運用改善まで支援できます。チームの開発速度を上げつつ、確認すべきリスクを見落とさない体制づくりから相談できます。

まとめ

AGENTS.mdは、Codexにチーム開発ルールを伝えるための重要な指示ファイルです。要点は次の3つです。

• READMEとは役割を分け、Codexが作業時に参照する編集ルール、テスト、レビュー観点を書く
• グローバル、プロジェクト、ディレクトリ単位の優先順位を理解し、近い場所ほど具体的な指示にする
• AGENTS.mdだけに頼らず、承認ポリシー、サンドボックス、チームレビューと組み合わせて運用する

AIzen株式会社では、Codexを前提にした開発フロー設計、AGENTS.md作成、AIレビュー基準、社内AI運用ルールの整備を支援しています。既存リポジトリに合わせて、AIに任せる範囲と人が確認する範囲を整理したい場合は、無料相談からご相談いただけます。