CodexのAGENTS.mdとは？作成方法と活用法も解説

Codexを使い始めてから「AGENTS.md」という言葉を見聞きする機会が増え、何なのか気になっている人は多いですよね。

ただ、実際にどう使えばいいのか、そもそも必要なのか判断できない人もいるはず。

そこでこの記事では活用例も交え、CodexにおけるAGENTS.mdの特徴を解説します。「使うべきか」の判断方法や効かないときの対処法も紹介するので、ぜひ参考にしてください。

CodexのAGENTS.mdとは？

AGENTS.mdとは、Codexに対して「どのように振る舞うか」を指示するMarkdown形式の設定ファイルです。

プロジェクトのルートや特定のディレクトリに配置すると、Codexがコードを生成・修正する際の行動ルールを制御できます。

たとえば「テストは必ずpytestで実行する」「import文はアルファベット順に並べる」といったルールを記述しておけば、Codexは指示に従って作業を進めます。

人間がコードレビューで毎回指摘していた細かなルールを、あらかじめファイルに書いておける仕組みです。口頭やチャットで繰り返し伝える手間がなくなり、チーム全体でコーディング規約を統一できます。

AGENTS.mdはリポジトリにコミットして共有できるため、メンバーが増えてもルールのブレが起きにくい点も大きなメリットです。Codexを活用するなら、まず理解しておきたいファイルといえます。

Codexの特徴を詳しく知りたい人は、次の記事を参考にしてください。

Codex・AGENTS.mdの活用例

AGENTS.mdに書くルールは自由度が高く、プロジェクトの課題に合わせて柔軟に設定できます。

ここからはAGENTS.mdの活用例を、3つにまとめて解説します。

テストの自動実行

AGENTS.mdにテスト実行のルールを書いておくと、Codexがコード変更のたびにテストを自動で走らせてくれます。

たとえばPythonプロジェクトなら、次のように記述します。

“`
# テストルール
コードを変更したら必ず `pytest` を実行すること
テストが失敗した場合は修正してから完了とすること
“`

このルールがあれば、Codexはコードを書き換えた後に自動でpytestを実行します。テストが通らなければ、自ら修正を試みてくれます。

開発者がテスト実行を忘れてバグを見逃すリスクを減らせるため、品質を保ちたいプロジェクトにおすすめです。

PR前のLintチェック

プルリクエスト（PR）を出す前にLintチェックを必須にするルールも、AGENTS.mdで設定できます。

Lintとは、コードのスタイルや文法の問題を自動で検出するツールです。次のように記述すると、Codexはコード整形を済ませてからPRを作成します。

“`
# Lintルール
PRを作成する前に `ruff check –fix` と `ruff format` を実行すること
Lint警告が残っている状態でPRを出さないこと
“`

チームでコードスタイルがバラバラになる問題は、レビュー負荷の増大につながります。AGENTS.mdにLintルールを明記しておけば、スタイルの統一が可能です。

依存追加時の確認徹底

新しいライブラリを追加する際に、ライセンスやバージョンの確認を必須にするルールも効果的です。

“`
# 依存管理ルール
新しいパッケージを追加する場合はpyproject.tomlに記載すること
MITまたはApache-2.0ライセンスのパッケージのみ使用可
追加後は `pip install -e .` で動作確認すること
“`

意図しないライセンスのライブラリが混入すると、あとから法的リスクが発覚するケースがあります。AGENTS.mdで制約をかけておけば、Codexが依存追加時に自動でルールを守るため、確認漏れを防げます。

CodexのAGENTS.mdは使うべき？

AGENTS.mdの導入は、すべてのプロジェクトに必須ではありません。開発体制やプロジェクトの規模に応じて判断するのがおすすめです。

ここからは導入すべきケースと不要なケースを、2つに分けて解説します。

こんな開発環境におすすめ

AGENTS.mdは、次のような開発環境でとくに効果を発揮します。

チーム開発では、メンバーごとにコードの書き方やテストの流れがバラつきがちです。AGENTS.mdにルールを集約しておけば、Codexがチーム共通のルールに従って動くため、レビュー時の指摘が減ります。

また、すでにLintやテストのコマンドが決まっているプロジェクトなら、ルールをそのまま転記するだけで導入できます。新たに運用フローを変える必要がない点もメリットです。

使わなくても良いケース

一方で、次のような状況ではAGENTS.mdの優先度は低いといえます。

個人で小さなスクリプトを書く場合、わざわざルールファイルを用意する手間が成果に見合わないケースもあります。まずはCodexの操作に慣れてから、必要に応じて導入を検討するのがおすすめです。

「ルールを決めるほどの規模か」を基準に判断すると、導入の要否を見極めやすくなります。

Codex・AGENTS.mdの作成方法

AGENTS.mdの作成は、コマンド1つで雛形を生成するところから始められます。

ここからはAGENTS.mdの作成方法を、4つのステップに分けて解説します。

1. ‘/init’で雛形を作成する
2. 配置場所を決める
3. ルールを追記する
4. 読み込みを確認する

1.’/init’で雛形を作成する

まずは、.’/init’で雛形を作成しましょう。

Codexには、AGENTS.mdの雛形を自動生成する`/init`コマンドが用意されています。ターミナルでCodexを起動し、チャット欄に次のコマンドを入力するだけです。

```
/init
```

OpenAIの公式ドキュメントによると、このコマンドを実行するとプロジェクトの構成が自動で解析されます。AGENTS.mdの初期テンプレートも同時に生成される仕組みです。

たとえばPythonプロジェクトなら、pytestやruffの実行コマンドがあらかじめ記載された状態で出力されます。ゼロから書く必要がなく、初心者でもすぐに取りかかれるのが魅力です。

2.配置場所を決める

次は、AGENTS.mdの配置場所を決めましょう。

AGENTS.mdは配置するディレクトリによって適用範囲が変わります。主な配置パターンは次の2つです。

たとえば`frontend/`と`backend/`でルールを分けたい場合は、それぞれのディレクトリにAGENTS.mdを置きます。ルート直下のAGENTS.mdが全体ルール、サブディレクトリのAGENTS.mdが局所ルールとして機能します。

下層のAGENTS.mdはルート直下のルールに加えて適用されるため、上書きではなく「追加」として扱われる点に注意してください。

3.ルールを追記する

雛形が生成されたら、プロジェクト固有のルールを追記していきます。記述はMarkdown形式で、見出しと箇条書きを組み合わせるのがベストです。

記述例を紹介します。

“`
# コーディング規約
変数名はスネークケース（snake_case）で統一する
関数のdocstringはGoogle形式で記載する

# テスト
テストファイルは `tests/` ディレクトリに配置する
カバレッジ80%以上を維持する

# 禁止事項
print文をデバッグ目的で残さないこと
グローバル変数の使用は禁止
“`

ポイントは、ルールを具体的なコマンドや数値で書くことです。「きれいなコードを書く」のような曖昧な指示は、Codexが解釈しにくいため避けましょう。

4.読み込みを確認する

ルールを書き終えたら、Codexが正しくAGENTS.mdを読み込んでいるか確認します。確認方法はシンプルで、Codexに直接質問するのが手軽です。

“`
このプロジェクトのAGENTS.mdに書かれているルールを教えて
“`

Codexが記述したルールを正しく回答すれば、読み込みは成功しています。回答にルールが反映されていない場合は、配置場所やファイル名のスペルミスを確認してください。

また、実際にコード修正を依頼して、ルールどおりの挙動になるかテストするのも有効な方法です。

【ケース別】AGENTS.mdが効かないときの対処法

AGENTS.mdを作成したのにCodexがルールを無視する場合、いくつかの原因が考えられます。OpenAIの公式ドキュメントで示されている仕様をもとに、よくある原因と対処法を把握しておきましょう。

ここからはAGENTS.mdが効かないときの対処法を、5つにまとめて解説します。

置き場所が対象外になっている

最も多い原因は、AGENTS.mdがCodexの検索対象外のディレクトリに置かれているケースです。

Codexは、カレントディレクトリからルートに向かってAGENTS.mdを探索します。リポジトリのルート直下、または作業対象のサブディレクトリに配置されていないと読み込まれません。

たとえば`docs/`フォルダの中にAGENTS.mdを置いても、`src/`配下のコード修正時には適用されません。ファイルの場所をリポジトリのルート直下に移動して、再度動作を確認しましょう。

別ファイルに上書きされている

Codexは複数の設定ファイルを参照するため、別の設定ファイルがAGENTS.mdのルールを上書きしているケースがあります。

たとえば`.codex/`ディレクトリ内のinstructions.mdやsystem promptの設定が、AGENTS.mdの記述と矛盾していると、意図した動作にならない場合があります。

対処法は、AGENTS.md以外の設定ファイルを確認し、ルールが競合していないかチェックすることです。競合が見つかったら、優先したいルールをAGENTS.mdに集約しましょう。

下層のルールが優先されている

サブディレクトリにもAGENTS.mdを配置している場合、下層のルールが上層のルールより優先される仕様に注意が必要です。

たとえばルート直下のAGENTS.mdに「インデントはスペース4つ」と書いていても、`frontend/AGENTS.md`に「インデントはスペース2つ」と書かれていれば、`frontend/`配下ではスペース2つが適用されます。

意図しない上書きが起きていないか、各ディレクトリのAGENTS.mdを横断的に確認しましょう。不要な下層ファイルは削除するか、ルート直下のファイルに統合すると管理がシンプルです。

32KiB超で切り捨てられている

OpenAIの公式ドキュメントによると、AGENTS.mdには32KiBのファイルサイズ上限があり、超過した部分は切り捨てられます。ルールを大量に書き込んだ結果、後半の記述が無視されている可能性があります。

対処法は次の2つです。

ターミナルで`ls -la AGENTS.md`を実行すれば、ファイルサイズをすぐに確認できます。32KiBは日本語で約1万6,000文字に相当するため、通常の運用では超えにくい量です。ただしテンプレートをコピー&ペーストで追加し続けると、超過するケースがあります。

CODEX_HOMEがずれている

環境変数`CODEX_HOME`が意図しないディレクトリを指していると、Codexがグローバル設定を正しく読み込めず、AGENTS.mdの挙動に影響が出ることがあります。

`CODEX_HOME`は、Codexがユーザーレベルの設定ファイルを探すベースディレクトリです。デフォルトでは`~/.codex/`が使われますが、環境変数で別の場所に変更していると、意図しない設定が適用される場合があります。

ターミナルで`echo $CODEX_HOME`を実行し、出力されたパスが正しいか確認してください。設定を変更した覚えがなければ、環境変数を未設定（デフォルト）に戻すことで解決するケースが多いです。

CodexのAGENTS.mdによく抱く疑問

ここからは、AGENTS.mdの運用で多く寄せられる疑問に回答します。

日本語で書いても問題ない？

AGENTS.mdは、日本語で記述しても問題なく動作します。CodexのベースとなるLLM（大規模言語モデル）は日本語を理解できるため、ルールを日本語で書いてもCodexは内容を正しく解釈してくれます。

ただし、コマンド名やファイルパスなどは英語のまま記述するほうが誤解を防げます。たとえば「pytestを実行する」と書くのは問題ありませんが、「パイテストを実行する」と書くとCodexが正しく認識できないリスクがあります。

ルールの説明文は日本語、コマンドやパスは英語という使い分けがおすすめです。

別のファイル名でも使える？

ファイル名は、必ず「AGENTS.md」にする必要があります。Codexは起動時にAGENTS.mdという名前のファイルを自動検索する仕組みのため、別の名前では認識されません。

たとえば「agents.md」（小文字）や「AGENT.md」（複数形でない）では読み込まれない場合があります。大文字・小文字やスペルを正確に守ることが重要です。

なお、GitHub Copilotでは類似の仕組みとして`.github/copilot-instructions.md`が使われます。ツールごとに設定ファイルの名前や仕様が異なるため、混同しないよう注意してください。

まとめ

今回は、CodexにおけるAGENTS.mdの活用方法を解説しました。

まずは小さなプロジェクトで`/init`コマンドを実行し、生成された雛形にプロジェクト固有のルールを追記するところから試してみましょう。慣れてきたら配置場所を使い分けるなど、より細かい制御にも挑戦してみてください。