はじめに
OpenAI Codex を使い始めると、AGENTS.md、config.tomlなど、いくつかの設定ファイルを目にします。
初めて見ると「どれが何のためのファイルなのか分からない」と感じるかもしれません。
まずは、それぞれの役割を簡単に整理してみます。
| ファイル | 役割 |
|---|---|
| AGENTS.md | Codex に対する作業ルールや開発方針を記載する |
| config.toml | Codex の動作設定を記載する |
簡単に言うと、
- AGENTS.md → 「AIへの指示書」
- config.toml → 「Codexの設定ファイル」
です。
特に AGENTS.md は、人間向けのドキュメントのように見えますが、実際には Codex が読み取って行動方針を理解するための重要なファイルです。
本記事では、OpenAI公式ドキュメントをもとに、AGENTS.md の概要から具体的な書き方まで分かりやすく解説します。
AGENTS.mdとは
AGENTS.md は、Codex に対してプロジェクト固有のルールや開発方針を伝えるためのファイルです。
例えば次のような内容を記載できます。
- コーディング規約
- テスト実行方法
- ビルド方法
- プロジェクト構成
- PR作成時のルール
- 開発上の注意事項
Codex は作業開始時に AGENTS.md を読み込み、そこに書かれた内容を考慮してコード生成や修正を行います。
人間の新しいメンバーがプロジェクトに参加した際に README を読むように、Codex も AGENTS.md を読んでプロジェクトのルールを理解するイメージです。
なぜAGENTS.mdが必要なのか
AIは優秀ですが、プロジェクトごとのルールまでは知りません。
例えば同じ Python プロジェクトでも、
- pytest を使う
- unittest を使う
- Black を利用する
- Ruff を利用する
- 型ヒント必須
- 型ヒント不要
など様々なルールがあります。
何も指定しなければ Codex は一般的なベストプラクティスを推測して作業します。
しかし AGENTS.md があれば、
- 「このプロジェクトでは Ruff を利用する」
- 「テストは pytest を実行する」
- 「新規コードには型ヒントを付ける」
といったルールを事前に伝えることができます。
結果として、手戻りが減り、よりプロジェクトに適したコードを生成できるようになります。
AGENTS.mdの特徴
公式ドキュメントでは、AGENTS.md は次のような特徴を持つファイルとして説明されています。
- Markdown形式で記述する
- 人間も AI も読むことを想定する
- リポジトリ内に複数配置できる
- ディレクトリごとにルールを分けられる
- 子ディレクトリの設定はその配下に適用される
つまり巨大なモノレポでも、
/
├─ AGENTS.md
├─ frontend/
│ └─ AGENTS.md
└─ backend/
└─ AGENTS.md
のような構成が可能です。
フロントエンドとバックエンドで異なるルールを設定できます。
AGENTS.mdに書くべき内容
公式では、Codex が効率的に作業できるよう、以下のような情報を記載することが推奨されています。
プロジェクト概要
まずはプロジェクトの目的を説明します。
# Project Overview
このプロジェクトはECサイトのバックエンドAPIです。
FastAPIを利用しています。
Codex が全体像を理解しやすくなります。
開発環境
セットアップ方法を記載します。
# Setup
pip install -r requirements.txt
または
poetry install
のように記載します。
ビルド方法
# Build
npm run build
# Build
make build
などです。
テスト実行方法
Codex が変更後に確認できるように記載します。
# Test
pytest
あるいは
# Test
npm test
リント・フォーマット
コード品質ツールを明記します。
# Lint
ruff check .
ruff format .
コーディング規約
重要なルールを記載します。
# Coding Guidelines
- 型ヒントを必ず付与する
- docstringを記載する
- printをコミットしない
アーキテクチャ説明
プロジェクト構成を説明します。
# Architecture
app/
├─ api/
├─ service/
├─ repository/
└─ model
これにより Codex が適切な場所へコードを追加できます。
良いAGENTS.mdを書くコツ
公式ドキュメントでも、曖昧な表現より具体的な記載が推奨されています。
例えば、
- 悪い例
テストを実施してください
- 良い例
変更後は以下を実行してください
pytest tests/
失敗した場合は原因を修正してください
こちらの方が Codex は適切に行動できます。
AGENTS.mdで避けたいこと
AGENTS.md は万能ではありません。
次のような内容は避けた方がよいでしょう。
良い感じに実装してください
適切に判断してください
なるべく頑張ってください
このような曖昧な指示は、人間でも解釈が分かれます。
Codex にも同じことが言えます。
できるだけ具体的に、
- 何をするか
- 何をしないか
- どのコマンドを実行するか
を書いておくことが重要です。
初心者向けサンプル
Python プロジェクトであれば、まずは次の程度から始めるのがおすすめです。
# Project Overview
このプロジェクトはFastAPIを利用したWeb APIです。
# Setup
pip install -r requirements.txt
# Test
pytest
# Lint
ruff check .
ruff format .
# Coding Guidelines
- 型ヒントを付ける
- docstringを記載する
- 既存の実装方針に合わせる
- 不要な依存ライブラリを追加しない
# Architecture
app/
├─ api/
├─ service/
├─ repository/
└─ model``````
まずはこのレベルでも十分効果があります。
運用しながら、
- 命名規約
- レビュー方針
- テスト方針
- ディレクトリ構成
などを追加していくとよいでしょう。
AGENTS.mdはいつ読み込まれるのか
Codex は作業を開始する前に AGENTS.md を読み込み、その内容をプロンプトへ取り込みます。
つまり、ユーザーが毎回チャットで
- このプロジェクトは FastAPI を使っています
- テストは pytest を使います
- 型ヒントは必須です
と説明しなくても、AGENTS.md に記載しておけば Codex が事前に理解した状態で作業を始めてくれます。
また、Codex はグローバルなルールとプロジェクト固有のルールを組み合わせて利用できます。
例えば、
- どのプロジェクトでも共通の開発ルール
- このリポジトリだけの独自ルール
を分離して管理できます。
これにより、どのリポジトリを開いても一貫した開発スタイルで Codex を利用できます。
読み込むタイミング
Codex は起動時に「命令チェーン（Instruction Chain）」を構築します。
この処理は通常、
- Codex セッション開始時
- Codex Cloud タスク開始時
に実行されます。
AGENT.mdの読み込み順序
読み込み順序には明確なルールがあります。
最初に、Codex はホームディレクトリ配下のAGENT.mdを確認し、その次に、プロジェクトスコープのAGENT.mdを読み込みます。
ホームディレクトリ配下のAGENT.mdには
- グローバルなルール
- すべてのリポジトリで共通のルール
を記載しておき、プロジェクトスコープのAGENT.mdには
- プロジェクト固有のルール
を記載をしておくと良いでしょう。
1. グローバルスコープ
まず Codex はホームディレクトリ配下を確認します。
優先順位は次の通りです。
AGENTS.override.md
↓
AGENTS.md
最初に見つかった空でないファイルのみが利用されます。
つまり、
~/.codex/
├─ AGENTS.override.md
└─ AGENTS.md
の場合は、
AGENTS.override.md
だけが利用されます。
AGENTS.md は読み込まれません。
Windowsではどこに配置するのか
Windows 環境の場合、通常は以下の場所になります。
C:\Users\<ユーザー名>\.codex\
例:
C:\Users\Taro\.codex\
├─ AGENTS.md
PowerShell であれば
$HOME\.codex
に相当します。
グローバルルールを定義したい場合は、この場所に AGENTS.md を配置します。
例えば、
# Global Rules
- 日本語で回答する
- Pythonは型ヒント必須
- テストを実行してから完了報告する
のようなルールを記載できます。
2. プロジェクトスコープ
次に Codex はプロジェクト側の AGENTS.md を探します。
通常は Git リポジトリのルートから開始し、現在の作業ディレクトリまで順番に探索します。
例えば、
project/
├─ AGENTS.md
└─ backend/
├─ AGENTS.md
└─ api/
└─ user.py
で user.py を編集する場合、
以下の順で探索されます。
project/AGENTS.md
↓
project/backend/AGENTS.md
つまり、
- 共通ルール
- サブシステム固有ルール
を自然に分離できます。
AGENTS.override.mdとは
AGENTS.mdのほかに
AGENTS.override.md
が利用できます。
優先順位は次の通りです。
AGENTS.override.md
↓
AGENTS.md
同じディレクトリに両方存在する場合は、
AGENTS.override.md
のみが利用されます。
AGENTS.mdはどのように結合されるのか
Codex は見つけた AGENTS.md を単純に上書きするわけではありません。
ルートディレクトリ側から順番に連結していきます。
例えば、
project/
├─ AGENTS.md
└─ backend/
└─ AGENTS.md
ルート側:
- Pythonを利用する
- pytestを利用する
backend側:
- FastAPIを利用する
の場合、
Codex が受け取る内容は概念的には次のようになります。
- Pythonを利用する
- pytestを利用する
- FastAPIを利用する
となります。
このとき、ルート側の指示よりbackend側の指示の方が優先度高くなります。
現在の作業場所に近い AGENTS.md がより強く影響します。
ディレクトリごとにルールを分けるメリット
例えばモノレポ構成の場合、
project/
├─ AGENTS.md
├─ frontend/
│ └─ AGENTS.md
└─ backend/
└─ AGENTS.md
とすることで、
共通ルール
- テストを実行する
- コミット前にLintを実行する
フロントエンド専用ルール
- React Hooksを利用する
- TypeScriptを必須とする
バックエンド専用ルール
- FastAPIを利用する
- Pydanticでバリデーションする
のような管理ができます。
大規模プロジェクトほど効果を実感しやすいでしょう。
AGENTS.md利用時の注意点
AGENTS.md にはサイズ制限があります。
Codex は空のファイルを自動的に無視します。
また、読み込む AGENTS.md の総サイズが上限に達すると、それ以降のファイルは読み込まれません。
デフォルトでは約 32KiB が上限です。
そのため、
- 開発ルール
- アーキテクチャ
- テスト方法
- コーディング規約
程度であれば問題ありませんが、
設計書を丸ごと貼り付けるような使い方は避けた方がよいでしょう。
サイズ制限に達した場合
サイズ上限に達した場合は次の方法が推奨されています。
1. 上限値を引き上げる
Codex の設定で
project_doc_max_bytes
を変更します。
2. AGENTS.mdを分割する
例えば、
project/
├─ AGENTS.md
├─ frontend/
│ └─ AGENTS.md
└─ backend/
└─ AGENTS.md
のようにディレクトリごとへ分散させます。
こちらの方が保守性も高く、公式ドキュメントでも推奨される運用方法です。
おわりに
AGENTS.md は、Codex にプロジェクトのルールや背景を伝えるための重要なファイルです。
特別な記法を覚える必要はなく、Markdown 形式で「新しく参加した開発者に伝えたい内容」を書くだけで利用できます。
最初はシンプルな内容でも構いません。
- プロジェクト概要
- セットアップ手順
- テスト方法
- コーディング規約
この4つを書くだけでも、Codex の出力品質は大きく向上します。
また、プロジェクトが成長するにつれて AGENTS.md も育てていくことが重要です。実際に Codex を使いながら、「毎回説明していること」「何度も修正していること」を AGENTS.md に追加していくことで、より自分のスタイル(もしくは、チームの開発スタイル)に合った AI エージェントへと成長していきます。
Codex を導入したばかりの方は、まずは小さな AGENTS.md を作成し、自分たちのプロジェクトのルールを少しずつ記載してみてください。きっと、AIとの協業がよりスムーズになるはずです。