CodexのAGENTS.mdには、プロジェクトの前提と確認手順を書きます。最初に用意したいのは、担当フォルダ、変更してはいけない範囲、ビルド・テストの実行場所です。文章を増やすより、コードの変更後に確認できる条件を少数に絞ると、指示の保守が楽になります。
このページでは、AGENTS.mdを1枚保存し、Codexが参照する指示と実際のテスト結果を照合するところまで進めます。ルート・子フォルダの優先順位と、読み込まれない場合の確認表も用意しました。
公式資料の確認日：2026年10月29日。構成とテンプレートは練習用で、親子の指示を変える実機比較や遵守率の測定は未実施です。
AGENTS.mdに何を書くか
AGENTS.mdは、毎回の依頼に共通する説明をリポジトリ側へ置くためのファイルです。「このアプリは何か」「どこにコードがあるか」「変更後に何を実行するか」を、プロジェクトに参加した人にも分かる言葉で書きます。基本操作を知りたい場合はCodexの使い方を先に読んでください。
まずREADMEと package.json を確認します。既存の説明とAGENTS.mdが食い違わないようにするためです。たとえばREADMEでは pnpm test、AGENTS.mdでは npm test と書くと、どちらを使うべきかが曖昧になります。使うパッケージ管理ツールや必要な環境は、実際のリポジトリに合わせてください。
# このプロジェクト
- ブラウザ用の問い合わせフォームを作る教材です。
- UIは src/、テストは test/ にあります。
# 変更の方針
- 依頼された動作に必要な変更だけを行ってください。
- 既存の無関係な変更は保持してください。
- 外部サービスへの送信と本番公開は、この教材では扱いません。
# 確認
- プロジェクトのルートで npm test を実行してください。
- UIを変えたときは通常入力・空入力・長文入力を確認してください。
- 実行できない確認は理由を報告し、成功扱いしないでください。
# 報告
- 変更した動作、変更ファイル、確認結果を短く説明してください。
この例は package.json にtestスクリプトがあるプロジェクト向けです。ルートに AGENTS.md として保存する前に、src/・test/の実際の名前と確認コマンドを置き換えます。ファイルを保存してもテスト自体は作られないため、空入力など必要なケースを検査できるかも確認してください。
ルートと子フォルダの優先順位
OpenAIのAGENTS.mdガイドでは、Codexは起動時に個人用とプロジェクト用の指示を組み立てると説明されています。プロジェクトではルートから現在の作業場所へ向かって読み、作業場所に近い指示が後に適用されます。同じディレクトリでは AGENTS.override.md が通常の AGENTS.md より優先されます。読込サイズの上限や代替ファイル名の設定もあります。
sample/
AGENTS.md
frontend/
AGENTS.md
package.json
backend/
AGENTS.md
package.json
このような構成なら、ルートには全体の目的、frontendにはブラウザ画面の確認、backendにはサーバー側の確認を書きます。ルートから起動しただけで、すべての子フォルダの指示が開始時に読み込まれると期待しないことが大切です。作業場所を明確にして開始し、対象領域の指示を確認します。
frontend/ の入力フォームを修正します。
まだ変更せず、現在の作業場所と、今回適用するAGENTS.mdの場所を説明してください。
親と子の指示に矛盾があれば、該当箇所を挙げてください。
たとえばルートの「標準の確認はnpm test」に対し、frontendの「このフォルダではnpm run test:uiを使う」は領域を限定した指示です。ところがルートで「すべての箇所で必ずnpm testだけを使う」と強く書くと、矛盾を増やします。全体ルールに不要な「必ず」「例外なく」を足さず、適用範囲を明示しましょう。
ビルド・テストコマンドの記述例
AGENTS.mdにビルドとテストを書くときは、作業ディレクトリ、コマンド、何を確かめるかの3点をそろえます。次はフロントエンドの例です。
# frontend/ の確認手順
1. frontend/ を作業ディレクトリにする。
2. npm test で入力値の検証を確認する。
3. npm run build で配布用ビルドが作れるか確認する。
4. フォームの見た目を変えたときはブラウザで確認する。
5. 失敗したコマンドとエラーの概要を報告する。
# フォーム変更時の確認ケース
- 通常の名前：送信前の検証を通る。
- 空文字と空白のみ：必須エラーになる。
- 上限を超えた文字列：長さのエラーになる。
「テストを実行した」だけでは、新しい不具合を見つけられるとは限りません。空白だけの名前を許してしまう問題なら、テストにも空白だけの入力を追加します。正常な名前1つだけのテストが通っても、その不具合は見逃されます。
ビルドとテストの役割も分けます。ビルド成功は、必要なファイルを生成できたことの確認です。ボタンを押したときに適切なエラーが表示されるかは、別の検査が必要になります。CIで実行する内容が分かるなら、それと同じ条件をAGENTS.mdにも記録すると、手元とのずれを調べやすくなります。
CodexがAGENTS.mdを読み込まないとき
読み込まれない原因を探す順序は、ファイルの存在、作業場所、優先される別ファイル、内容の長さです。いきなり設定全体を書き換えるより、1項目ずつ確認します。
| 症状 | 最初に確認すること | 次の対応 |
|---|---|---|
| ルールを説明できない | ファイル名と保存先 | 対象ディレクトリで開始し直す |
| 古い指示が出る | セッション開始後に編集したか | 新しい実行で読み直す |
| 内容が違う | AGENTS.override.mdがあるか | 通常ファイルとの役割を整理する |
| 末尾のルールが抜ける | ファイル群が長すぎないか | 重複を削り、領域ごとに分ける |
| 名前を変えたファイルが無視される | 代替名の設定 | 通常のAGENTS.mdへ戻して確認する |
公式資料では指示の組み立ては実行開始時に行われるとされています。編集後も同じセッションで古い説明が続くなら、新しい実行で確認するのが切り分けになります。ファイルを削除したり設定を広く変更したりする前に、対象ファイルだけを読み比べてください。
なお、Codexが「読みました」と答えても、実際の作業結果の確認は必要です。変更差分に対象外ファイルが含まれていないか、指定コマンドの結果が報告されているかを見ます。AGENTS.mdは権限を強制的に制限する仕組みの代わりにはなりません。
長くなった指示を整理する練習
次のような文章が増えてきたら、具体的な失敗に対応する短いルールへ書き換えます。
変更前：
常に丁寧に考え、あらゆる問題を予測し、できるだけ高品質な成果物を作ってください。
何度も確認し、最高のコードになるまで作業してください。
変更後：
入力検証を変更したら、空文字・空白のみ・通常入力・長文入力をテストする。
テストが失敗した場合は、変更前からの失敗か今回の変更で生じた失敗かを報告する。
後者は短い一方で、何を実行し、何を報告するかが決まっています。ルールを足す前に「この文でどんな誤りを防ぎたいか」を考えると、過剰な説明を減らせます。
| 変更後のレビュー項目 | 合格の目安 |
|---|---|
| コマンドの存在 | package.jsonやCIに対応する処理がある |
| 作業場所 | 別フォルダで誤実行しないよう書かれている |
| 矛盾 | 親子で同じ対象へ逆の要求をしていない |
| 機密情報 | パスワードやトークンの実値がない |
| 保守 | 古いコマンド・重複した文章が残っていない |
完成後は、対象フォルダで新しい実行を始め、使う確認コマンドを説明してもらいます。その後に小さな修正を依頼し、説明されたコマンドが実際に実行されたかを確認します。
AGENTS.mdの更新もGitの差分としてレビューします。コードだけを更新して確認コマンドの説明が古いまま、という状態を防ぐためです。Claude Codeも使う場合は、名前が似ていても読込仕様を同じと決めつけず、CLAUDE.mdの書き方を参照してください。
参考資料と確認範囲
- OpenAI：Custom instructions with AGENTS.md — 読込順序・override・確認方法。2026年10月29日確認。
- テンプレートとチェック表は本サイトの作例。Codexの複数回実験、実測遵守率、UIごとの表示差は未検証です。
本文執筆：Codex ／ 確認・編集：制作担当