はじめに
「毎回同じ説明をCodexに伝えるのが手間」
「プロジェクトのコーディング規約をCodexに覚えてほしい」
「AGENTS.mdってCLAUDE.mdと何が違うの？」
こうした疑問を持っている方に向けて、この記事ではCodexのAGENTS.mdの仕組みと書き方を詳しく解説します。AGENTS.mdはプロジェクトのルートに置くだけでCodexが自動的に読み込む「AIへの指示書」です。
前回のCLIのインストールと使い方でCodexを動かせるようになった方は、この記事でAGENTS.mdを活用してさらに効率を上げましょう。
目次
- AGENTS.mdとは何か
- AGENTS.mdとCLAUDE.mdの違い
- AGENTS.mdの作成方法
- 書くべき内容と書き方のコツ
- プロジェクト別のテンプレート
- 階層配置と優先順位
- チームでの活用方法
- まとめ
1. AGENTS.mdとは何か
基本定義
AGENTS.md とは、プロジェクトのディレクトリに配置するMarkdownファイルです。Codexはタスク実行の開始時にこのファイルを自動で読み込み、記載された内容をプロジェクトの前提知識として作業を進めます。
OpenAIの公式ドキュメントでは以下のように説明されています。
「AGENTS.mdはREADME.mdに似たテキストファイルで、コードベースのナビゲート方法・テスト用に実行するコマンド・プロジェクトの標準的な実践に最もよく準拠する方法などをCodexに教えることができます」
人間に例えると、新しいプロジェクトに参加した開発者に渡す「プロジェクト概要書」や「開発ガイドライン」のようなものです。
なぜAGENTS.mdが重要か
| AGENTS.mdなし | AGENTS.mdあり |
|---|---|
| 毎回技術スタックを説明する | 自動で把握している |
| コーディング規約を毎回指示する | 最初から遵守している |
| テストコマンドを毎回伝える | 自動で実行できる |
| 禁止事項を忘れることがある | 常に守られる |
2. AGENTS.mdとCLAUDE.mdの違い
AGENTS.mdはCodex（OpenAI）用、CLAUDE.mdはClaude Code（Anthropic）用のプロジェクト設定ファイルです。
| 項目 | AGENTS.md | CLAUDE.md |
|---|---|---|
| 対応ツール | OpenAI Codex | Anthropic Claude Code |
| ファイル形式 | Markdown | Markdown |
| 配置場所 | プロジェクトルート・サブディレクトリ | プロジェクトルート |
| 読み込み | タスク実行開始時に自動読み込み | セッション開始時に自動読み込み |
| 役割 | ほぼ同じ（プロジェクトのAIへの指示書） | ほぼ同じ |
両方のツールを使う場合は、それぞれのファイルを同じプロジェクトに共存させることができます。共通する内容（技術スタック・コーディング規約）は同じ内容を記載し、ツール固有の設定（テストコマンド等）はそれぞれに適した形で記述するのが実践的なアプローチです。
3. AGENTS.mdの作成方法
手動で作成する
cd your-project
touch AGENTS.mdCodexに作成させる
Codexに「このプロジェクト用のAGENTS.mdを作って」と指示することもできます。
> このプロジェクトを分析して、適切なAGENTS.mdを作成してください。
技術スタック・テストコマンド・コーディング規約を把握した上でまとめてください。4. 書くべき内容と書き方のコツ
書くべき内容
① プロジェクトの概要
# プロジェクト概要
このリポジトリはタスク管理SaaSのバックエンドAPIです。
- 言語：Node.js 20 / TypeScript 5.3
- フレームワーク：Express 5
- データベース：PostgreSQL 15 / Prisma ORM
- テスト：Jest / Supertest
- CI/CD：GitHub Actions → AWS ECS② テストコマンド
Codexが自律的にテストを実行するために最も重要な情報です。
# テストコマンド
## 全テスト実行
npm test
## 単一ファイルのテスト
npm test -- src/services/userService.test.ts
## カバレッジレポート
npm run test:coverage
## Lintチェック
npm run lint
## 型チェック
npm run typecheck③ コーディング規約
# コーディング規約
- インデント：スペース2つ
- 変数名：camelCase
- 型定義：any禁止・unknownを使うこと
- コメント：日本語で記述
- エラーハンドリング：try-catchを省略しない
- console.log：本番コードに残さない④ 禁止事項
# 禁止事項
- .envファイルを編集しない
- データベースへの直接SQL操作をしない（ORMのみ使用）
- mainブランチへの直接コミットをしない
- 外部ライブラリを無断で追加しない
- テストなしで実装を完了させない⑤ プロジェクト固有の知識
# 重要な設計決定
## 認証
JWTではなくセッション認証を採用。
理由：ステートフルな認証がセキュリティ要件上必要なため。
詳細：docs/architecture/auth.md参照
## エラーレスポンス形式
すべてのエラーは以下の形式で返すこと：
{ "error": { "code": "ERROR_CODE", "message": "説明" } }書き方のコツ
- 箇条書きを中心にする：長文より短い箇条書きの方がCodexに読み込まれやすい
- 具体的なコマンドを書く：「テストを実行して」という指示より
npm testの方が確実 - 200〜500行程度に収める：長すぎると処理負荷が増える
- 定期的に更新する：プロジェクトの変化に合わせてメンテナンスする
5. プロジェクト別のテンプレート
Next.js プロジェクト向けテンプレート
# プロジェクト概要
Next.js 14（App Router）で構築されたECサイトのフロントエンドです。
## 技術スタック
- Next.js 14 / TypeScript 5.3
- Tailwind CSS / shadcn/ui
- TanStack Query / Zustand
- Vitest / React Testing Library
- Vercelにデプロイ
# テストコマンド
npm run test # Vitestでテスト実行
npm run test:ui # UIモードでテスト実行
npm run lint # ESLint
npm run typecheck # TypeScript型チェック
npm run build # ビルド確認
# 開発ルール
## コンポーネント設計
- Server ComponentsとClient Componentsを適切に分離する
- 'use client'ディレクティブは最小限にする
- コンポーネントはsrc/components/以下に配置
## ファイル命名
- コンポーネント：PascalCase（例：ProductCard.tsx）
- フック：useXxx形式（例：useProductList.ts）
- ユーティリティ：camelCase（例：formatPrice.ts）
# 禁止事項
- any型の使用
- src/app/以下のLayout・Pageコンポーネントへの直接ロジック記述
- useEffectでのデータフェッチ（TanStack Queryを使うこと）
- console.logの本番コードへの残留Python / FastAPI プロジェクト向けテンプレート
# プロジェクト概要
FastAPI + PostgreSQLで構築された決済APIサービスです。
## 技術スタック
- Python 3.12 / FastAPI 0.115
- SQLAlchemy 2.0 / Alembic
- pytest / httpx
- Docker / AWS ECS
# テストコマンド
pytest # 全テスト実行
pytest tests/unit/ # ユニットテストのみ
pytest -k "test_payment" # 特定テストの実行
pytest --cov=app --cov-report=html # カバレッジ
ruff check . # Lint
mypy app/ # 型チェック
# 開発ルール
## 型ヒント
- すべての関数に型ヒントを付ける（anyは使わない）
- PydanticモデルはBaseModelを継承する
## データベース
- SQLAlchemyのORMを使う（生SQLは原則禁止）
- マイグレーションはAlembicで管理する
- 接続プーリングはSQLAlchemyのデフォルト設定を使う
# 禁止事項
- .envファイルへの直接アクセス（config/settings.pyを経由すること）
- 本番DBへの直接操作
- パスワードのログ出力6. 階層配置と優先順位
サブディレクトリへのAGENTS.md配置
AGENTS.mdはプロジェクトルートだけでなく、サブディレクトリにも配置できます。
project/
├── AGENTS.md ← プロジェクト全体のルール
├── frontend/
│ └── AGENTS.md ← フロントエンド固有のルール
└── backend/
└── AGENTS.md ← バックエンド固有のルールCodexはタスクの対象ディレクトリに応じて適切なAGENTS.mdを読み込みます。モノレポ構成で複数のサービスが共存するプロジェクトで特に有効です。
読み込みの優先順位
サブディレクトリのAGENTS.mdはプロジェクトルートのAGENTS.mdの内容を上書きではなく追加する形で機能します。両方の内容が適用されます。
7. チームでの活用方法
Gitで管理する
AGENTS.mdをGitリポジトリにコミットして管理することで、チーム全員が同じルールをCodexに適用できます。
git add AGENTS.md
git commit -m "docs: add AGENTS.md for Codex project settings"プルリクエストで変更をレビューする
AGENTS.mdの変更はコードの変更と同様にPRを通じてレビューする運用を推奨します。AIへの指示の変更はチームの開発方針に関わるためです。
チームの共通ルールと個人設定の分離
AGENTS.mdはチームルールのみを記載します。個人の好みの設定（返答の文体・説明の詳しさ等）は個人のユーザーホームディレクトリに配置する形で分離することを推奨します。
8. まとめ
AGENTS.mdとは：
- プロジェクトルートに置くMarkdownファイル
- Codexがタスク実行開始時に自動で読み込む「プロジェクト指示書」
- 技術スタック・テストコマンド・コーディング規約・禁止事項を記載する
最低限書くべき内容：
- 技術スタック（言語・フレームワーク・DB）
- テストコマンド（Codexが自律テストを実行するために必須）
- コーディング規約（命名規則・インデント等）
- 禁止事項（触れてほしくないファイル・操作）
CLAUDE.mdとの関係：
- 同じプロジェクトに両方共存させることが可能
- 共通内容は同じ、ツール固有の設定はそれぞれに記述
次回のComputer Use機能の活用法と注意点では、CodexがPCを自律操作する機能の使い方を解説します。
よくある質問（FAQ）
Q. AGENTS.mdは必須ですか？
A. 必須ではありません。AGENTS.mdなしでもCodexは動作しますが、プロジェクト固有の情報を毎回説明する必要があります。AGENTS.mdを設定することで、一貫性のある作業品質を維持できます。
Q. AGENTS.mdに書いた内容はCodexに確実に守られますか？
A. 高い確率で守られますが、100%ではありません。特に重要な制約（本番DBに触れない等）は、パーミッション設定でも合わせてブロックすることをお勧めします。
この記事はCodex活用シリーズです。← CLIの使い方 ｜ Computer Use →
ご質問はお問い合わせページからお気軽にどうぞ。
