OpenAI Codex を本格的に使い始めると、こういう不満が出てきます。
- 「またデプロイ方法を毎回説明する羽目になる…」
- 「禁止しているライブラリを勝手に入れてくる…」
- 「コメントを英語で書かないでって何回言わせるの…」
これらを 一発で解決するのが AGENTS.md です。プロジェクトルートに置くだけで、Codex は 毎回それを読み込んで作業の前提 にしてくれます。
この記事では、AGENTS.md の役割・書き方・実例を完全解説します。
AGENTS.md とは？
AGENTS.md は、Codex（および Claude Code など）に「このプロジェクトのルール・前提・禁止事項」を伝えるための Markdown ファイルです。
- プロジェクトのルート（
package.jsonと同じ階層）に置く - ファイル名は 完全一致で
AGENTS.md - Markdown 形式で自由に書ける
- Codex はセッション開始時にこれを読み込み、以降のすべての応答で参照
これがあるとないとで、Codex の出力品質が 体感で2〜3倍 変わります。
何を書くべきか：5つの定番セクション
セクション1：プロジェクトの全体像
# プロジェクト概要
このリポジトリは、フルーツの旬を月別に紹介するアフィリエイトサイトです。
- Next.js 16 (App Router)
- Cloudflare Workers でホスト
- TailwindCSS v4 でスタイル
- D1（SQLite）でデータ管理
Codex は 最初に「これは何のプロジェクト？」を理解する ことで、的外れな提案を避けられます。
セクション2：守ってほしいルール
# 守ってほしいルール
- コメントは必ず日本語で書く
- 1行は120文字以内に収める
- TypeScript の `any` 型は禁止
- ファイル末尾は必ず改行で終わる
- セミコロンは必須
「何度も指摘される点」は全部ここに書いておくと再発しません。
セクション3：禁止事項
# 禁止事項
- 新しいライブラリを追加するときは必ず事前に提案
- `node_modules/` 配下は絶対に編集しない
- DBスキーマの変更は提案のみ（自動実行禁止）
- `.env.local` の中身を読まない / 出力しない
セキュリティ・運用上クリティカルな部分は 明示的に禁止 することで、事故を防げます。
セクション4：よくある作業の手順
# よく使うコマンド
- 開発サーバー起動：`npm run dev`
- ビルド：`npm run build`
- デプロイ：`npm run deploy`
- テスト実行：`npm test`
- 型チェック：`npm run typecheck`
# デプロイの注意
- デプロイ前に `npm run build` でビルドが通ることを必ず確認
- Cloudflare の `preview_urls = false` を維持
Codex が 「テストを実行して」 と言われたときに、自動で npm test を打てるようになります。
セクション5：ファイル構成の説明
# ディレクトリ構成
- `app/` — Next.js のページ・ルーティング
- `components/` — UIコンポーネント
- `lib/` — ユーティリティ関数
- `content/blog/` — 記事の Markdown ファイル
- `scripts/` — ビルド/デプロイ補助スクリプト
# どこに何を書くか
- 新しいページ → `app/[ルート名]/page.tsx`
- 共通コンポーネント → `components/`
- DBアクセス → `lib/db.ts` に集約
Codex がファイルを作るとき、自動で正しい場所に置いてくれる ようになります。
完成サンプル：個人ブログ向け AGENTS.md
# プロジェクト概要
個人運営のテックブログ。
- Next.js 16 (App Router)
- Cloudflare Workers でデプロイ
- TailwindCSS v4
- 記事は `content/blog/*.md` で管理
# コーディング規約
- TypeScript 必須、`any` 禁止
- React Server Components を優先
- フォントは `font-sans` のみ（`font-serif` 禁止）
- 色は CSS variables（`var(--primary)` など）を使う
# よく使うコマンド
| コマンド | 用途 |
|---|---|
| `npm run dev` | 開発サーバー |
| `npm run build` | ビルド |
| `npm run deploy` | Cloudflare へデプロイ |
| `npm run admin` | ローカル管理画面（http://localhost:3301） |
# 禁止事項
- `.env.local` の内容を表示しない / 編集しない
- `node_modules/` を直接編集しない
- ライブラリ追加は事前に確認
- 既存記事の本文は許可なしに編集しない
# よくある作業
## 新規記事を追加するとき
- `content/blog/[slug].md` を作成
- frontmatter は date / title / description / category / tags が必須
- 本文は 6000字以上を目安に
- 内部リンクは `/blog/[slug]/` 形式
## デプロイ手順
1. `npm run build` で問題ないか確認
2. `npm run deploy` で本番反映
3. デプロイ後 5分以内に URL を開いて確認
このくらい書いておくと、Codex は 熟練の同僚 のように振る舞います。
書き方の8つのコツ
1. 「やってほしい」より「やってほしくない」を優先
肯定的な指示は守られやすいですが、禁止事項のほうが実害を防げる。「セミコロン必須」より「セミコロンなしのコードを書かないで」のほうが効きます。
2. 具体的なファイルパスを書く
「適切な場所に置いて」より「components/ 配下に置いて」のほうが正確。
3. コマンド例を添える
「ビルドしてください」より「npm run build を実行」のほうが Codex は迷いません。
4. プロジェクト固有の用語を定義
「当ブログでは "記事" とは Markdown ファイル1本を指します」のように、自分たちの言葉を明示。
5. 長すぎる AGENTS.md は逆効果
500行を超えると Codex の応答が遅くなったり、肝心な部分が薄まったりします。重要な30%だけ に絞る。
6. 例を入れる
「Bad: let x: any = 1;」「Good: let x: number = 1;」のように 悪い例と良い例 を併記すると効果絶大。
7. 更新を続ける
プロジェクトの方針が変わったら必ず AGENTS.md も更新。古い指示が残ると Codex が混乱します。
8. チームで共有
AGENTS.md は git管理下 に置き、チーム全員で共通の指示書にします。誰が Codex を使っても同じ品質が出るように。
Claude Code との互換性
AGENTS.md は OpenAI Codex 専用ではなく、Anthropic Claude Code でも読み込まれます（一部は CLAUDE.md という別ファイルを優先）。
Claude Code と Codex の比較 も参照してください。
両方使っている場合：
AGENTS.md：共通ルールCLAUDE.md：Claude Code 固有の指示（必要なら）
の使い分けが便利です。
階層化の活用
AGENTS.md は ルート以外のフォルダにも置けます。
/AGENTS.md # プロジェクト全体のルール
/frontend/AGENTS.md # フロントエンド固有のルール
/backend/AGENTS.md # バックエンド固有のルール
Codex は作業対象のフォルダ内の AGENTS.md を 追加で参照 します。モノレポで言語・フレームワークが分かれる場合に便利。
効果の測り方
AGENTS.md を整備したら、こんな観点で効果を確認してみてください。
- ✅ 同じ質問を繰り返さなくなったか
- ✅ 禁止していることを Codex がやらなくなったか
- ✅ ファイルが正しい場所に作られるか
- ✅ コメント・命名が規約通りか
- ✅ プロジェクト固有のコマンドを覚えているか
3〜5項目に「Yes」が増えるたび、AGENTS.md の投資対効果は計り知れません。
やってはいけない使い方
機密情報を書かない
# 絶対NG例
APIキー: sk-xxxxxxxxxxxx
DBパスワード: secret123
AGENTS.md は 誰でも見えるリポジトリ内 のファイル。秘密情報は環境変数で管理しましょう。
古い情報を放置しない
「Next.js 12 を使っています」と書いたまま Next.js 16 に上げると、Codex が古い API を提案してきます。
矛盾する指示を入れない
「コメントは英語で」「コメントは日本語で」のような矛盾があると、Codex の応答が不安定になります。
ここまでの要点を1枚にまとめました。
AGENTS.mdを含む、公式推奨のトークン節約テクニックは トークンを節約する方法（公式推奨5選） で全体像を確認できます。
よくある質問（FAQ）
Q. ファイル名は AGENTS.md 大文字小文字を区別しますか？
A. AGENTS.md（全部大文字） が標準。agents.md や Agents.md でも読まれることが多いですが、推奨は大文字。
Q. JSON や YAML 形式ではダメですか？
A. Markdown が公式仕様。LLMがMarkdownを最も自然に解釈できるためです。
Q. AGENTS.md を git にコミットすべき？
A. 必ずコミット。チーム全員で共有してこそ意味があります。
Q. Codex以外のAIにも使えますか？
A. AGENTS.md という慣習自体はオープン。Claude Code や Cursor の Composer なども参照する場合があります。
Q. プロンプトに毎回書くのと何が違う？
A. 毎回書くより楽、トークン消費が減る、指示の抜けが防げる、チーム共有が容易 という4つのメリットがあります。
AGENTS.md の公式仕様・最新情報は Codex公式ドキュメント でも確認できます。
まとめ
AGENTS.md は Codex の精度を劇的に上げる、たった1ファイル です。「プロジェクト概要・コーディング規約・禁止事項・コマンド・ディレクトリ構成」の5セクションを書いておくだけで、Codex は熟練の同僚のように振る舞います。
