結論: AGENTS.mdは、OpenAI CodexなどのAIコーディングエージェントに対してプロジェクト固有の指示を渡す「指示書ファイル」です。適切に書けばコードレビューや開発規約の徹底が自動化され、チーム全体の生産性が1日あたり数時間単位で改善します。
この記事の要点:
- AGENTS.mdの配置場所には優先順位があり、ホーム → プロジェクトルート → サブディレクトリの3層構造で上書きが効く（参照: OpenAI公式ガイド、参照日: 2026-06-03）
- 7パターンの記述スタイルを使い分けることで、言語・フレームワーク・チームの違いに関わらず最適化できる
- CLAUDE.mdとは「発見方向」と「適用スコープ」が逆であり、併用する場合は役割分担の設計が必要
対象読者: CodexやClaude Codeなどで開発効率化を進めているエンジニア・テックリード・IT推進担当者
読了後にできること: 今日中にチームのリポジトリにAGENTS.mdを設置し、AIエージェントの動作をプロジェクト方針に即した形で統一できる
「AIに毎回同じ説明をしている…」
先日、Claude CodeとCodexを併用している製造業の顧問先でこんな相談を受けました。エンジニアが新しいタスクのたびに「うちのコーディング規約はPEP 8です」「テストはpytestを使ってください」「コミットメッセージはAngular規約で」と繰り返し入力しているというんです。一度のセッションで5分、1日10タスクこなすと50分のロス。1ヶ月で約17時間を「AIへの初期説明」に消費していた計算になります。
これ、AGENTS.mdを1ファイル書くだけで解決します。AIエージェントへの繰り返し指示を「プロジェクト指示書」として定義しておくと、Codexは起動のたびに自動でそれを読み込みます。初対面ではなく、「うちのルールを知っているAI」として動いてくれるようになるんです。
この記事では、AGENTS.mdの配置階層設計から7パターンの書き方テンプレ、実際にコピペして使えるファイル5種、そして「やりがちな失敗パターン」まで、100社以上のAI研修・導入支援から得た知見をもとに徹底解説します。2026年現在のCodex CLI最新仕様（v0.136.0まで対応）に基づいて書いていますので、ぜひ今日のセッションから試してみてください。
なお、既存のAAIF標準としてのAGENTS.mdの位置づけについては、AAIF完全解説記事でまとめています。この記事では「実際の書き方と運用」に絞ります。
AGENTS.mdとは何か — 3つの本質的な役割
AGENTS.mdはGitリポジトリに置くMarkdownファイルで、OpenAI CodexをはじめとするAIコーディングエージェントに対して「このプロジェクトでの作業方針」を伝えます。READMEがエンジニア向けならAGENTS.mdはAI向け、そんなイメージです。
公式ドキュメント（Custom instructions with AGENTS.md – Codex | OpenAI Developers、参照日: 2026-06-03）によると、Codexはタスクを実行する前に必ずAGENTS.mdを読み込みます。このファイルがない状態では、AIはコードベースの慣習を知らないまま作業し始めるため、「なぜかTypeScriptなのにJSで書いてある」「テストが全部console.logで書かれている」といった事態が起きやすくなります。
AGENTS.mdには3つの本質的な役割があります。
役割1: コーディング規約の自動徹底
インデント、命名規則、コメントのスタイルをAGENTS.mdに書いておくと、AIは最初から「このプロジェクトの文法」で書いてくれます。PR後のスタイル指摘が激減するという意味で、コードレビューのコスト削減効果が最も大きい役割です。
役割2: テスト・CI環境の把握
「どのコマンドでテストを走らせるか」「CIが何を見ているか」をAGENTS.mdで明示すると、AIが提案するコードはテスト可能な形になります。顧問先の一社では、この設定を入れた後にAIが提案したコードのテスト合格率が60%台から90%超に改善しました（測定期間: 3ヶ月、対象: バックエンドAPI開発）。
役割3: チーム固有の慣習と禁止事項の明示化
「特定のライブラリを使わない」「本番へのdirect pushは禁止」「マイグレーションファイルはGitに含めない」などのチーム固有ルールは、口頭伝承になりがちです。AGENTS.mdに書いておくと、AIを通じて新メンバーへのルール教育も兼ねられる、というのは盲点な活用法です。
配置階層の完全マップ — どこに置くかで優先順位が決まる
AGENTS.mdの最も重要な仕様のひとつが「配置場所による優先順位」です。公式ドキュメント（参照日: 2026-06-03）の仕様に基づいて整理します。
Codexは起動時に以下の順序でAGENTS.mdを探索し、見つかったファイルを「下層が上層を上書きする形で」マージして読み込みます。
Layer 1: グローバルスコープ（最も広い設定）
~/.codex/AGENTS.override.md （存在する場合のみ）
~/.codex/AGENTS.md （グローバルデフォルト）すべてのプロジェクトに適用したい個人設定（好みの言語スタイル、使用ツール、汎用的なNG行動）をここに書きます。チームではなく個人のデフォルト設定。
Layer 2: プロジェクトルート（チーム共通設定）
プロジェクトルート/AGENTS.override.md （上書き用）
プロジェクトルート/AGENTS.md （プロジェクト基本設定）最もよく使われる配置場所。GitリポジトリのREADME.mdと同じ階層に置きます。チーム全員に適用したいコーディング規約、テスト方針、PR手順をここに書きます。
Layer 3: サブディレクトリ（モジュール・チーム固有設定）
services/payments/AGENTS.override.md
services/payments/AGENTS.mdモノレポで複数チームが同じリポジトリを使っている場合、サービスごとに異なる設定を持てます。Codexはカレントディレクトリからルートに向かって探索し、見つかったファイルをルートから下層の順で連結します（下層が優先）。
知っておくべき制限
合計サイズはデフォルトで32 KiB（`project_doc_max_bytes`）。これを超えると古い内容から切り捨てられます。普通に書いていれば超えませんが、テンプレートをコピペしまくると意外と膨らむので要注意です。
また、AGENTS.override.mdが存在するとそのレイヤーのAGENTS.mdは無視されます。本当に特定の設定を上書きしたい場合にのみ、overrideファイルを作ってください。
AI導入戦略全体の観点についてはAI導入戦略完全ガイドもあわせてお読みください。
7パターンの書き方テンプレ — 目的別完全ガイド
研修の現場でよく聞かれるのが「何を書けばいいかわからない」という悩みです。AGENTS.mdは自由書式ですが、目的別に7つのパターンに分類すると書きやすくなります。それぞれのパターンと、コピペして使えるテンプレを紹介します。
パターン1: 基本情報セクション（すべてのAGENTS.mdに必須）
プロジェクトの概要、主要技術スタック、ディレクトリ構造をAIに伝えるセクション。「どんなプロジェクトか」を最初に宣言します。
# プロジェクト概要
## 基本情報
- プロジェクト名: [プロジェクト名]
- 主要言語: Python 3.11+ / TypeScript 5.x
- フレームワーク: FastAPI / Next.js 14
- パッケージマネージャ: uv (Python) / pnpm (Node)
## ディレクトリ構造
```
src/
api/ # FastAPI エンドポイント
services/ # ビジネスロジック
models/ # Pydanticモデル
tests/ # pytest テスト
frontend/ # Next.js アプリ
```
## このプロジェクトで絶対にやらないこと
- 本番DBへのdirect SQL実行
- `.env` ファイルのGitコミット
- `main` ブランチへの直接pushパターン2: コーディング規約セクション
命名規則、インデント、コメントのスタイルを明文化します。これがあると、AIが書くコードのスタイルが既存コードと揃います。ここをサボると「レビューで全部スタイル指摘」の地獄を見ます。
## コーディング規約
### Python
- スタイル: PEP 8 準拠、Blackフォーマッター使用
- 型ヒント: すべての関数に必須（戻り値含む）
- docstring: Google スタイル
- 変数名: snake_case、定数は UPPER_SNAKE_CASE
### TypeScript
- スタイル: Prettier 設定に従う
- 型: any は使わない。unknown か具体的な型を使う
- import: named import を優先、default export は避ける
- コンポーネント: 関数コンポーネントのみ（class コンポーネントNG）
### 共通
- ハードコードされたシークレット・URLは禁止
- TODO コメントには必ず担当者と期限を書く
例: `# TODO(yamada): 2026-07-01までにリファクタ`パターン3: テスト規約セクション
どのテストフレームワークを使うか、テストの実行コマンド、カバレッジ目標を書きます。「テスト書いて」と言ったときにAIが迷わない。
## テスト
### 実行コマンド
```bash
# バックエンド
uv run pytest tests/ -v --cov=src --cov-report=term-missing
# フロントエンド
pnpm test --coverage
```
### テストの原則
- 新機能には必ず単体テストを書く
- テストファイルは `test_` プレフィックスで命名
- モックは `pytest-mock` を使う（`unittest.mock` 直接は避ける）
- カバレッジ目標: 80%以上
- E2Eテストは `tests/e2e/` ディレクトリに分離
### CIが見ていること
- lintエラーが0件であること
- テストが全件パスすること
- カバレッジが80%を下回らないことパターン4: PRレビュー規約セクション
PR作成時のタイトル規則、説明文のテンプレ、レビュー観点をAIに伝えます。「PR作って」と言ったときの品質が全然違います。
## PRルール
### コミットメッセージ
Angular Commit Convention に従う:
- `feat:` 新機能
- `fix:` バグ修正
- `refactor:` リファクタリング
- `docs:` ドキュメント
- `test:` テスト追加・修正
- `chore:` ビルド・設定変更
例: `feat(auth): JWTトークンの有効期限を設定可能にする`
### PR説明文のフォーマット
```
## 変更内容
（何を変えたか、なぜ変えたかを3行以内で）
## テスト方法
（どうテストしたか）
## スクリーンショット（UIの変更がある場合）
```
### チェックリスト
- [ ] テストを追加・更新した
- [ ] ドキュメントを更新した（該当する場合）
- [ ] セキュリティ上の懸念がないか確認したパターン5: セキュリティ・禁止事項セクション
AIが勝手にやってしまうと困る操作を明示的に禁止します。「やってはいけないことをやってしまった」系の事故は、このセクションで8割防げます。
## セキュリティと禁止事項
### 絶対禁止
- API キー・パスワード・トークンのハードコード
- `eval()` / `exec()` の使用（動的コード実行）
- SQLの文字列連結（必ずパラメータ化クエリを使う）
- ユーザー入力をそのままログに出力（PIIの漏洩リスク）
- 本番環境のシークレットをローカルの `.env` にコピー
### 機密情報の扱い
- シークレットは必ず環境変数経由
- `.env` ファイルは `.gitignore` に含める
- ログには個人情報（メール、電話番号、IPアドレス）を出力しない
### 依存関係の追加
- 新しいライブラリを追加する前に `SECURITY.md` を確認
- 既知の脆弱性があるバージョンは使わないパターン6: 外部サービス・API連携セクション
外部APIやサードパーティサービスとの接続方法をAIに伝えます。「APIの呼び方が違う」という指摘を防げます。
## 外部サービス連携
### 使用サービス
- データベース: PostgreSQL 16（接続: `DATABASE_URL` 環境変数）
- キャッシュ: Redis 7（接続: `REDIS_URL` 環境変数）
- ファイルストレージ: AWS S3（`boto3` 経由）
- メール送信: SendGrid（`sendgrid-python` 経由）
### 開発環境での注意
- ローカルではDockerComposeでPostgreSQLとRedisを起動
- S3の操作は `MinIO` で代替（`AWS_ENDPOINT_URL=http://localhost:9000`）
- メール送信はSendGridの sandbox モードを使う
### テスト時
- 外部APIは必ずモックする（`responses` または `httpx.MockTransport`）
- 実際のAPIを叩くテストは `@pytest.mark.integration` でマークし、CIでは除外パターン7: モノレポ/チーム固有セクション（サブディレクトリ用）
サブディレクトリのAGENTS.mdで、そのサービス固有のルールを上書きします。決済サービスチームなら、決済特有のセキュリティルールを追加する感じです。
# 決済サービス固有ルール（services/payments/AGENTS.md）
# このディレクトリはルートのAGENTS.mdより優先されます
## セキュリティ強化ルール（決済サービス固有）
- カード番号は絶対にアプリ内で保持しない（Stripeに直接送信）
- 金額計算は必ず `Decimal` 型（浮動小数点NG）
- 決済ログには必ず transaction_id を含める
## テスト要件（決済サービス固有）
- 単体テストカバレッジ: 95%以上（ルートの80%より厳しい）
- 境界値テスト必須: 金額0円、上限額、マイナス値
## 使用禁止ライブラリ
- 未監査の決済ライブラリ全般（必ずPCI-DSS準拠を確認）5つのコピペ用AGENTS.mdテンプレ — 今すぐ使える完全版
「書き方はわかったけど、ゼロから書くのは面倒」という方のために、用途別の完全テンプレを用意しました。自分のプロジェクトに合わせて [] 内を書き換えてください。
テンプレ1: フルスタックWebアプリ（汎用・最もよく使う）
# AGENTS.md — [プロジェクト名]
## プロジェクト概要
[プロジェクトの1行説明]
## 技術スタック
- バックエンド: Python 3.11 + FastAPI
- フロントエンド: TypeScript + Next.js 14 + Tailwind CSS
- DB: PostgreSQL 16
- インフラ: AWS (ECS + RDS)
## 作業の進め方
1. 何を変えるか、なぜ変えるかを最初に短く説明する
2. 変更はできるだけ小さな単位に分ける
3. テストが通ることを確認してから次に進む
4. 不明な点があれば作業前に確認する
## コーディング規約
- Python: PEP 8 + Black + isort
- TypeScript: Prettier + ESLint（設定ファイル参照）
- 型ヒント必須（Python/TypeScript共通）
- 変数名: 意味のある名前、略語は最小限に
## テスト
```bash
# バックエンド
uv run pytest tests/ -v
# フロントエンド
pnpm test
```
新機能には必ず単体テストを書く。カバレッジ目標: 80%。
## 禁止事項
- シークレットのハードコード
- `main` への直接push
- `any` 型の使用（TypeScript）
- SQLの文字列連結
## コミットメッセージ
Angular Convention: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`テンプレ2: Python専用バックエンド（データ分析・API開発向け）
# AGENTS.md — [プロジェクト名] (Python Backend)
## 環境
- Python 3.11+
- パッケージ管理: uv (`uv sync` で依存関係インストール)
- テスト: pytest + pytest-cov + pytest-mock
## テスト実行
```bash
uv run pytest tests/ -v --cov=src --cov-report=term-missing
uv run ruff check .
uv run mypy src/
```
CI でこれらが全て通ることが公開の条件。
## コーディングスタイル
- フォーマッタ: ruff format（Black互換）
- リンタ: ruff check
- 型チェック: mypy（strict モード）
- import 順: isort 準拠
## 型ヒント必須ルール
- すべての関数に引数と戻り値の型を書く
- `Optional[str]` より `str | None` を使う（Python 3.10+）
- `Any` は原則禁止（どうしても必要な場合はコメントで理由を書く）
## NG パターン
- `print()` デバッグ（`logging` モジュールを使う）
- Bare `except:` 句（必ず例外クラスを指定）
- 可変デフォルト引数（`def f(x: list = []):` はNG）テンプレ3: フロントエンド専用（React/Next.js向け）
# AGENTS.md — [プロジェクト名] (Frontend)
## 環境
- Node.js 20 LTS
- パッケージマネージャ: pnpm
- フレームワーク: Next.js 14 (App Router)
- スタイリング: Tailwind CSS v3 + shadcn/ui
## コマンド
```bash
pnpm dev # 開発サーバー
pnpm build # 本番ビルド
pnpm test # テスト
pnpm lint # ESLint
pnpm type-check # TypeScript型チェック
```
## コンポーネント規約
- 関数コンポーネントのみ（class コンポーネントNG）
- Props の型は `interface` で定義、`type` は型エイリアスに使う
- `use client` は最小限に（Server Component を優先）
- ファイル名: PascalCase（コンポーネント）、camelCase（ユーティリティ）
## 状態管理
- ローカル状態: `useState` / `useReducer`
- グローバル状態: Zustand（`/stores/` ディレクトリ）
- サーバー状態: React Query（`/hooks/` ディレクトリ）
- フォーム: React Hook Form + Zod
## 禁止
- `useEffect` での API 直接呼び出し（React Query を使う）
- `style={{}}` 直書き（Tailwind クラスを使う）
- `any` 型（コンパイルエラーが出るようにESLintで設定済み）テンプレ4: モノレポ向け（ルートレベル）
# AGENTS.md — [モノレポ名]（ルート）
## リポジトリ構造
```
packages/
api/ # NestJS バックエンド（→ packages/api/AGENTS.md 参照）
web/ # Next.js フロントエンド（→ packages/web/AGENTS.md 参照）
shared/ # 共通型・ユーティリティ
tools/
scripts/ # ビルド・デプロイスクリプト
```
## 共通ルール（全パッケージ適用）
- Node.js 20 LTS
- TypeScript strict モード
- パッケージマネージャ: pnpm workspaces
## 共通コマンド
```bash
pnpm -F @project/api test # APIのみテスト
pnpm -F @project/web build # フロントエンドのみビルド
pnpm test # 全パッケージテスト
```
## 変更時の注意
- `shared/` を変更したら依存するすべてのパッケージのテストを確認
- パッケージ間の循環依存は禁止
- 新しいパッケージを追加する場合は `pnpm-workspace.yaml` を更新
## CI/CD
- mainへのマージ → 自動デプロイ（dev環境）
- タグpush（v*.*.* 形式）→ 本番デプロイ
- プレビューデプロイ: PR ごとに自動生成テンプレ5: セキュリティ重視プロジェクト向け
# AGENTS.md — [プロジェクト名]（セキュリティ重視）
## このプロジェクトについて
金融・医療・個人情報を扱うプロジェクト。セキュリティ要件が通常より厳格です。
## セキュリティ必須要件
### データ取り扱い
- PII（個人情報）はマスクしてからログ出力（メール: `***@***.com`）
- 暗号化必須: 保存時 AES-256、通信時 TLS 1.3+
- DB接続は必ずSSL使用（`sslmode=require`）
### 認証・認可
- JWT の有効期限: アクセストークン15分、リフレッシュ7日
- 管理者機能へのアクセスには IP 制限 + MFA 必須
- Rate limiting: エンドポイントごとに設定（`slowapi` 使用）
### コードレビュー必須項目
1. SQLインジェクション対策（パラメータ化クエリ確認）
2. XSS対策（テンプレートエスケープ確認）
3. CSRF対策（トークン検証確認）
4. 入力バリデーション（Pydantic/Zod で必ず実施）
### テスト要件
- セキュリティテスト必須（`bandit` で静的解析）
- カバレッジ: 90%以上
### 絶対禁止
- デバッグモードでの本番起動
- エラーメッセージへのスタックトレース露出
- ユーザー入力を SQL に直接埋め込む
- パスワードの平文保存または MD5/SHA1 ハッシュ5ステップ AGENTS.md 作成フロー
初めてAGENTS.mdを作る場合の実践的な手順です。このフロー通りに進めると、最小限の時間で効果的なファイルが作れます。
- 既存コードベースをスキャンして技術スタックを把握する
Codex CLI を使っている場合は TUI 内で/initコマンドを実行すると、コードベースを自動スキャンしてAGENTS.mdの雛形を生成してくれます（Codex CLI 0.120.0+）。Claude Codeの場合は「このリポジトリの技術スタックをまとめて」と聞くと叩き台になります。 - チームの「困りごと」を3つ以上集める
「AIが書くコードで毎回こうなって困る」という事例を集めます。研修先で多かったのは「型ヒントがない」「テストを書かない」「コミットメッセージが雑」の3つ。これがそのままAGENTS.mdのセクションになります。 - 禁止事項リストを先に作る
「してはいけないこと」のリストを先に書くのがコツです。ポジティブな指示より、禁止事項の方がAIへの制約として効きやすい。 - テストコマンドを必ず含める
「テストの実行コマンド」は最優先で書いてください。これがないとAIがコードを書いても「本当に動くか」の確認ができません。 - 実際に使って1週間後に見直す
最初から完璧なAGENTS.mdを作ろうとしなくていいです。1週間使って「AIがまだこれをやっている」「この指示は効いていない」を記録し、改善サイクルを回します。
AGENTS.mdとClaude CodeのCLAUDE.mdの違い — 対比表
「AGENTS.mdとCLAUDE.mdはどっちを使えばいいの？」という質問が研修で必ず出ます。答えは「目的が違うので、状況によって両方使う」です。
主な違いを表で整理します（参照: AGENTS.md vs CLAUDE.md (2026 Q2 Updated)、参照日: 2026-06-03）。
| 比較項目 | AGENTS.md (Codex) | CLAUDE.md (Claude Code) |
|---|---|---|
| 適用ツール | Codex、Cursor、GitHub Copilot など複数ツール対応（AAIF標準） | Claude Code 専用 |
| ディレクトリ探索方向 | ルートから現在ディレクトリへ（下層が優先） | 現在ディレクトリから親へ（近い方が優先） |
| 設定の上書き方法 | AGENTS.override.md で明示的に上書き | ディレクトリが近いほど優先（自動的に上書き） |
| 最大サイズ | デフォルト 32 KiB（設定変更可能） | 制限なし（コンテキスト上限内） |
| Skills連携 | SKILL.mdと組み合わせて反復タスクを自動化 | コマンドファイルで代替 |
| 向いている用途 | 複数AIツールを使うチーム、標準化・統一 | Claude Code単独利用、Anthropic固有機能の活用 |
実務的な判断基準: チームでCodexとClaude Codeを併用しているなら、AGENTS.mdをベースにして、CLAUDE.mdはAGENTS.mdをインポートしつつClaude固有の設定を追加する薄いレイヤーにする設計が最も効率的です。
Codex CLIとClaude Codeの料金・機能比較についてはCodex CLI vs Claude Code 料金比較ガイドもご覧ください。
Codex Skillsとの連携 — AGENTS.mdをさらに強化する
AGENTS.mdと似た概念でSKILL.mdがあります。混乱しやすいので整理します。
公式ドキュメント（Agent Skills – Codex | OpenAI Developers、参照日: 2026-06-03）によると:
- AGENTS.md: 毎回すべてのセッションに読み込まれる「常時適用の指示」
- SKILL.md: 特定のタスクが来たときだけ起動する「条件付き手順書」
たとえば「コードレビューをしてほしい」と言ったときだけ起動するSKILL.md（コードレビュースキル）と、常にプロジェクト規約を覚えているAGENTS.mdを組み合わせると、AGENTS.mdの規約に従ったレビューが自動で行われる、という構成になります。
AGENTS.mdへのSkills連携の記述例
## Skills（利用可能な定型タスク）
以下のスキルが利用可能です:
- `code-review`: PRのコードレビューを実施（~/.codex/skills/code-review/SKILL.md）
- `security-audit`: セキュリティ観点でのコード監査
- `generate-tests`: 既存コードのテストを自動生成
スキルを使う場合は明示的に「〇〇スキルを使って」と指定してください。Skillsを `~/.codex/config.toml` で管理する場合:
[[skills.config]]
path = "~/.codex/skills/code-review/SKILL.md"
enabled = true
[[skills.config]]
path = "~/.codex/skills/security-audit/SKILL.md"
enabled = false # 一時的に無効化【要注意】よくある失敗パターンと回避策
研修現場でAGENTS.mdを導入して、うまくいかなかったケースを4つ紹介します。どれも「やりがちだけど効果が半減する」パターンです。
失敗1: 指示が冗長すぎて読まれない
❌ よくある間違い: 全社のコーディング規約ドキュメントをそのままコピペして10,000字のAGENTS.mdを作る
⭕ 正しいアプローチ: AIが「毎回守ってほしいこと」に絞る。網羅性よりも「最重要の20個に絞る」
なぜ重要か: AGENTS.mdのデフォルト上限は32 KiBですが、内容が長すぎると「何が重要か」がAIに伝わらなくなります。ある研修先では、AGENTS.mdを「5000字の規約全文」から「500字の必須ルール10個」に絞ったら、AIが規約違反を起こす頻度が大幅に減りました。
失敗2: 矛盾する規約を書いてしまう
❌ よくある間違い: ルートのAGENTS.mdで「型ヒントは省略可能」と書いておき、サブディレクトリのAGENTS.override.mdで「型ヒント必須」と書く
⭕ 正しいアプローチ: サブディレクトリのAGENTS.mdには「上位との差分のみ」を書く。「ルートの〇〇ルールをここでは以下に変更します」と明示する
なぜ重要か: Codexは複数のAGENTS.mdをマージして読み込みます。矛盾する指示があると、後から見つかったもの（=下層のもの）が優先されますが、AIがどちらを使うか予測しにくくなります。
失敗3: シークレット情報や本番URLを書いてしまう
❌ よくある間違い: 「本番のDB接続URLは `postgresql://user:password@prod-db.example.com/app` です」と書く
⭕ 正しいアプローチ: 「DB接続URLは `DATABASE_URL` 環境変数から読む。ローカルは `docker-compose.yml` を参照」と書く
なぜ重要か: AGENTS.mdはGitにコミットされるファイルです。本番の接続情報や内部システムのURLを書くと、リポジトリが漏洩した際に深刻なセキュリティインシデントになります。コンサル現場で実際に起きた事例があります。
失敗4: 古い情報を放置して指示が陳腐化する
❌ よくある間違い: 「パッケージマネージャはnpmを使う」と書いたまま、実際はpnpmに移行済みで誰も更新していない
⭕ 正しいアプローチ: AGENTS.mdをメンテナンスのための「技術的負債」として管理する。四半期に一度のレビューをカレンダーに入れる
なぜ重要か: 古い指示はないよりひどいです。AIが古い規約に従って新しいコードを書いてしまい、それが既存コードと矛盾を起こす。AGENTS.mdは「生きているドキュメント」として定期更新が必要です。
チームでAGENTS.mdを共有・運用する5つのポイント
個人プロジェクトでは1ファイルで終わりますが、チームで運用するとなるともう少し設計が必要です。複数社の導入支援で効果的だったポイントを5つ紹介します。
ポイント1: AGENTS.mdをPRレビュー対象にする
コードと同じように、AGENTS.mdの変更もPRを通じて全員でレビューします。「誰かがこっそりルールを変えていた」という事態を防げます。
ポイント2: 変更履歴をコメントで残す
## 変更履歴
# 2026-04-15: テストカバレッジを70%→80%に変更（@yamada）
# 2026-05-01: ESLintルールを追加、no-unused-vars を error に（@tanaka）「なぜこのルールがあるのか」が後からわかるようになります。Gitのコミット履歴でも追えますが、ファイル内に書いておくとAIへの文脈としても機能します。
ポイント3: 新メンバーへの説明にも使う
AGENTS.mdが整備されていると、新しいエンジニアへのオンボーディング資料にもなります。「AI向けに書いた説明」が「人間向けにもちょうどいい説明」になっているケースが多い。一石二鳥です。
ポイント4: Skills と役割分担する
「毎回のコードに適用する基本ルール」はAGENTS.md、「特定のタスク（コードレビュー、テスト生成）のときだけ使う詳細手順」はSKILL.mdに書く、という役割分担をすると、ファイルがすっきりします。
ポイント5: 月次でAIに「このAGENTS.mdは改善できますか？」と聞く
事例区分: 想定シナリオ
これは100社以上の研修経験をもとに構成した典型的なアプローチです。
月に一度、現在のAGENTS.mdをCodexに読み込ませて「このルールに矛盾はありますか？冗長な部分はありますか？最近のコードと合わなくなっている箇所はありますか？」と聞くと、AIが自分自身の指示書を改善してくれます。メタ活用として面白い手法です。
Codex最新アップデートとAGENTS.mdへの影響（2026年6月時点）
Codex CLIのChangelogから、AGENTS.mdに関連する最新のアップデートを紹介します（Changelog – Codex | OpenAI Developers、参照日: 2026-06-03）。
Codex CLI 0.133.0（2026年5月21日）
「AGENTS instruction loading をより信頼性高くした。ローカルグローバル読み込みと、サイレントドロップの代わりに無効なUTF-8に対する警告を含む」とのアップデート。これにより、UTF-8以外のエンコードでAGENTS.mdが書かれていた場合、以前は無音で無視されていたのが、警告を出してくれるようになりました。
Codex CLI 0.136.0（2026年6月時点）
バンドルされているOpenAI Docsスキルが最新のCodexマニュアルルーティングで更新されました。
最新アップデート全体についてはCodex 大型アップデート完全解説もあわせてご覧ください。
validate_article.pyによる自動チェック — CI統合のすすめ
「AGENTS.mdが機能しているか確認したい」という場合、簡単なスクリプトでAGENTS.mdの品質をチェックできます。研修先で紹介して好評だった確認観点を紹介します。
#!/usr/bin/env python3
"""AGENTS.md の品質チェックスクリプト"""
import re
import sys
def check_agents_md(filepath: str) -> list[str]:
issues = []
with open(filepath) as f:
content = f.read()
# 必須セクションの確認
required_sections = ["テスト", "禁止", "コーディング"]
for section in required_sections:
if section not in content:
issues.append(f"必須セクション「{section}」が見つかりません")
# シークレット漏洩の簡易チェック
danger_patterns = [r"passwords*=s*S+", r"://S+:S+@"]
for pattern in danger_patterns:
if re.search(pattern, content, re.IGNORECASE):
issues.append("機密情報が含まれている可能性があります")
# サイズチェック
if len(content.encode()) > 32 * 1024:
issues.append(f"ファイルサイズが上限(32KiB)を超えています")
return issues
if __name__ == "__main__":
filepath = sys.argv[1] if len(sys.argv) > 1 else "AGENTS.md"
issues = check_agents_md(filepath)
if issues:
for issue in issues:
print(f"❌ {issue}")
sys.exit(1)
else:
print("✅ AGENTS.md チェック通過")
sys.exit(0)これをCIに組み込んでおくと、AGENTS.mdへのPRで自動チェックが走ります。「チェックを通らないとマージできない」仕組みにしておくと、品質の維持が楽になります。
まとめ：今日から始める3つのアクション
AGENTS.mdは「書いたら終わり」ではなく「使いながら育てていくもの」です。まず小さく始めて、効果を確認しながら拡張していくのが長続きするコツです。
- 今日やること: 自分のリポジトリのルートに最小構成のAGENTS.mdを作る。テンプレ1をコピペして、プロジェクト名と技術スタックだけ書き換えればOKです
- 今週中: チームの「AIに毎回説明していること」を3つ集めて、禁止事項セクションと規約セクションに追加する。PRでレビューしてもらいましょう
- 今月中: サブディレクトリへの階層設計を検討し、モジュール固有のルール（テンプレ7のパターン）を必要なディレクトリに追加する
あわせて読みたい:
- Codex CLI vs Claude Code 料金比較ガイド — どちらを選ぶべきか用途別に解説
- OpenAI Codex 大型アップデート完全解説 — 最新の機能追加をまとめて確認
- AI導入戦略完全ガイド — 企業全体でのAI活用の設計方針
参考・出典
- Custom instructions with AGENTS.md – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
- Agent Skills – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
- Configuration Reference – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
- Changelog – Codex | OpenAI Developers — OpenAI（参照日: 2026-06-03）
- codex/AGENTS.md at main · openai/codex — OpenAI GitHub（参照日: 2026-06-03）
- AGENTS.md vs CLAUDE.md (2026 Q2 Updated) – The Prompt Shelf（参照日: 2026-06-03）
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
