Codexで同じシステムを何日もかけて直していると、「既存のCTRやCPCの計算は変えないで」「変更前に影響範囲を確認して」「APIキーをコードに直接書かないで」と、毎回同じ注意を書くことになります。一度きりの作業なら問題ありませんが、数か月続く開発では手間がかかり、書き忘れも起きます。
そこで調べたのが、CodexのAGENTS.mdです。この記事では、仕組みの基本と置き場所、書く内容の例、使うときの注意点を整理します。
この記事で分かること
- AGENTS.mdの役割と、プロンプト・Skillsとの違い
- 置き場所と、ファイルが読み込まれる順番
- 変更禁止箇所・テスト・承認ルールの書き方と注意点
AGENTS.mdとは
AGENTS.mdは、Codexがプロジェクトで作業するときに読む指示を、Markdown形式で書いておくファイルです。開発の方針、変更してはいけない箇所、テストの方法などを書いておくと、作業を始めるたびに読み込まれるため、毎回同じ説明をしなくて済みます。プロジェクトの「共通ルールブック」と考えると分かりやすいです。
| 方法 | 役割 | 例 |
|---|---|---|
| プロンプト | 今回の仕事を指示する | CPAの計算機能を追加して |
| AGENTS.md | プロジェクト全体で守るルール | コード変更後は必ずテストする |
| Skills | 特定の仕事の手順を使い回す | テストの進め方の手順書 |
AGENTS.mdは「守るべきルール」、Skillsは「仕事の進め方」と分けて考えると整理しやすくなります。なお、AGENTS.mdは会話の記録ではないため、設計の経緯や進み具合は別の資料に残しておく必要があります。
置き場所と読み込まれる順番
OpenAIの公式ドキュメントによると、AGENTS.mdは次の2か所に置けます。
- 自分用の共通ルール:Codexのホームフォルダ(通常は「~/.codex/AGENTS.md」)
- プロジェクト用のルール:プロジェクトの一番上のフォルダ(通常はGitの管理範囲の一番上)から、作業中のフォルダまでの各フォルダ
Codexは、上のフォルダから順にファイルをつなげて読みます。作業中のフォルダに近いファイルほど後ろに来るため、内容がぶつかった場合は近いほうが優先されます。たとえば、ルートには全体のルール、「src」フォルダには実装のルール、「tests」フォルダにはテストのルールを置く、という分け方ができます。
また、読み込める合計の大きさには上限があり、初期設定では32KiBです。上限に達すると、それ以降のファイルは読み込まれません。
書く内容の例
Meta広告の実績を集計する広告分析システムを例にすると、次のような内容が考えられます。
# 広告分析システム
## 目的
Meta広告の実績データを取得・整理し、広告別のKPIを分析する。
## 変更制限
以下は明示的な承認なしに変更しない。
- 既存のCTR・CPCの計算式
- データベースの構造
- 認証情報の管理方法
変更が必要な場合は、理由・影響範囲・代替案を示す。
## テスト
- コード変更後は既存テストを実行する(pytest)
- 結果を報告し、実行できなかったテストは理由を書く
## 承認が必要な作業
- 既存データの削除
- 本番環境への反映
- 新しい有料サービスの導入
承認前は、変更計画と影響範囲の整理までにする。
ポイントは、「品質を重視する」のような抽象的な方針で終わらせず、「テストを実行する」「理由・影響範囲・代替案を示す」のように、行動が分かる書き方にすることです。コードの書式のように機械的に確かめられる項目は、AIへの指示に頼らず、確認ツールに任せる方法もあります。
長くしすぎない
AGENTS.mdには多くのことを書けますが、API仕様や設計書まで全部入れると、更新が大変になり、大事なルールも埋もれます。AGENTS.mdには共通ルールだけを書き、詳しい設計は「docs」フォルダの別ファイルにまとめて、必要なときに参照するよう指示する形が管理しやすいです。
私はCodexではまだAGENTS.mdを作っていませんが、Claude Codeでは同じ役割のCLAUDE.mdを使っています。CLAUDE.mdには全作業に共通する原則だけを書き、ブログや広告などの細かい手順は別のルールノートに分け、必要な作業のときだけ読ませています。Codexでも同じ考え方で分けるつもりです。
ルールは一度作って終わりではありません。テスト不足で既存機能を壊した、APIキーをログに出してしまった、といった失敗があれば、その都度ルールを足していきます。
使うときの注意点
1つ目は、AGENTS.mdはAIの行動を技術的に止める仕組みではないことです。書いたルールが必ず守られるとは限らず、AIが誤って読み取ることもあります。重要なファイルは、Gitでの履歴管理、Codexの権限設定、テスト、人間による差分の確認と組み合わせて守ります。
2つ目は、APIキーやパスワードを書かないことです。認証情報は専用の管理方法で扱います。
3つ目は、外部から取ってきたプロジェクトに入っているAGENTS.mdの確認です。不適切な指示が含まれていないか、使う前に中身を読みます。
※記事作成時点(2026年11月)の情報です。置き場所や読み込みの仕組みは変わることがあるため、最新の情報はOpenAIの公式ドキュメントをご確認ください。
まとめ
CodexのAGENTS.mdは、プロジェクト全体で守るルールをファイルにしておき、作業のたびにAIへ読ませる仕組みです。毎回の注意の書き忘れを防ぎ、作業する日が変わっても同じ方針で開発を続ける助けになります。
ただし、ルールを書けば安全になるわけではありません。共通ルールに絞って短く保ち、Gitやテスト、人間の確認と組み合わせ、実際の失敗から少しずつ直していく、という順番で使っていこうと考えています。

