CODEX / REPOSITORY INSTRUCTIONS
指示は、書く内容だけでなく「どこに置くか」で効き方が変わる。
CodexのAGENTS.mdとは、Codexが作業前に読み込む継続的な指示ファイルです。最初はリポジトリルートに短い1枚を置き、全リポジトリ共通または一部ディレクトリだけの指示が生じた時に分けると、適用範囲を管理しやすくなります。
本記事では、書く内容、配置場所、AGENTS.override.mdを含む探索・優先関係、反映されない場合の確認順を、OpenAI公式情報と筆者の判断基準に分けて整理します。
こんな人におすすめ
- Codexへ毎回同じ指示を書いている人
- ルートとサブディレクトリのどちらへ置くか迷う人
AGENTS.override.mdの優先関係を知りたい人- ファイルを編集しても反映されない人
30秒で結論｜AGENTS.mdは最初にルートへ置く
Codexはプロジェクトルートから現在の作業ディレクトリまでAGENTS.mdを探索するため、最初の1枚をルートへ置けばリポジトリ全体の基準として扱えます。
OpenAI公式ドキュメントでは、プロジェクトルートは通常Gitルートであり、そこから現在の作業ディレクトリまで指示ファイルを探索すると説明されています。OpenAI公式「Custom instructions with AGENTS.md」
ただし、全リポジトリ共通の好みはCodexホーム、一部のディレクトリだけに効かせる規約はそのディレクトリへ置く方が、変更範囲と指示の責任を対応させやすくなります。
DECISION / INITIAL SETUP
repository/AGENTS.mdから始める
ルートの1枚には、リポジトリ全体で共通するコマンド、実装規約、禁止事項、完了条件だけを書きます。
- 全リポジトリ共通の個人設定が生じたらCodexホームへ分ける
- 特定サービスだけ違う規約が生じたら、そのディレクトリへ分ける
- 同じ階層の通常ファイルを置き換える場合だけ
AGENTS.override.mdを選ぶ
SCROLL → 横にスクロールできます
| 適用したい範囲 | 配置先 | 選ぶ条件 |
|---|---|---|
| 開く全リポジトリ | ~/.codex/AGENTS.md |
個人共通の作業方針を継承させる |
| 1つのリポジトリ全体 | repository/AGENTS.md |
最初の1枚として選ぶ |
| 特定ディレクトリ以下 | repository/service/AGENTS.md |
上位と異なる規約がある場合だけ分ける |
| 同じ階層の通常指示を置換 | AGENTS.override.md |
通常ファイルと併用せず、同一階層で優先させる |
~/.codexですが、CODEX_HOMEを設定している場合はその場所が基準になります（2026年8月確認）。CodexのAGENTS.mdとは？製品・モデルとの違い
CodexのAGENTS.mdとは、Codexが作業前に読み込み、リポジトリの構成・実行方法・禁止事項などを継続的な指示として受け取るMarkdownファイルです。
AGENTS.mdは、Codexのモデル名や料金プランではありません。毎回の依頼だけでは伝わりにくいリポジトリ固有の前提を、作業開始時の指示チェーンへ加える役割を持ちます。OpenAI公式AGENTS.md解説
Codex・モデル・AGENTS.mdの関係
AGENTS.mdはCodexが参照する指示ファイルであり、Codexという製品や、その中で使用されるモデルそのものではありません。
OpenAI公式用語集では、AGENTS.mdの指示はCodexのデスクトップアプリ、CLI、IDE拡張機能、Cloudに関係するものとして案内されています（2026年8月確認）。提供面は変わり得るため、公開後はOpenAI公式用語集で再確認します。
Codexそのものの入口やCLI・IDE・Cloudの選び方は、Codex全体の始め方とCLI・IDE・Cloudの選び方で分けて確認できます。
SCROLL → 横にスクロールできます
| 対象 | 役割 | AGENTS.mdとの関係 |
|---|---|---|
| Codex | コードベースを理解し、変更や確認を進めるコーディングエージェント | AGENTS.mdを作業前に読み込む側 |
| モデル | Codexの処理に使用されるモデル | AGENTS.mdそのものではない |
| AGENTS.md | 継続的なリポジトリ指示を記録するMarkdownファイル | 構成、コマンド、規約、禁止事項、完了条件をCodexへ伝える |
AGENTS.mdには何を書く？最小構成は6項目
筆者の判断基準では、CodexのAGENTS.mdは構成・コマンド・実装規約・禁止事項・完了条件・レビュー基準の6項目から必要なものだけを書くと管理しやすくなります。
6項目という分類はOpenAI公式の固定テンプレートではなく、公式例とベストプラクティスを初心者が作業へ移しやすい形に統合したものです。長い説明よりも、Codexが実行または確認できる指示を優先します。
最初の1枚に書く6項目
最初のAGENTS.mdには、Codexが「どこを編集し、何を実行し、何をもって完了とするか」を判断できる項目を置きます。
- 1. リポジトリ構成 主要ディレクトリの役割と、編集対象を探す起点を書く。
- 2. 実行コマンド インストール、ビルド、テスト、lintの正しいコマンドを書く。
- 3. 実装規約 命名、使用する仕組み、既存パターンの優先条件を書く。
- 4. 禁止事項 変更してはいけない領域と、事前確認が必要な操作を書く。
- 5. 完了条件 必要なテスト、差分確認、ドキュメント更新を定義する。
- 6. レビュー基準 レビューで検出する問題と、安全な代替手段を書く。
OpenAI公式は、ルールを簡潔にし、問題として指摘する動作と安全な代替手段・例外を説明するよう案内しています。フォーマットやlintで機械的に検出できるものはCIへ任せるという切り分けも示されています。OpenAI公式「Add code review rules」
条件と確認方法をセットで書く
「品質を高くする」ではなく、「JavaScriptを変更したらnpm testを実行する」のように、条件と行動を対応させます。
OpenAI公式のベストプラクティスでも、AGENTS.mdは短く実用的に保ち、Codexが繰り返す失敗を見つけたら指示として追加する方針が示されています。OpenAI公式Codex best practices
Node.js向けAGENTS.mdテンプレート
次の例は、一般的なNode.jsプロジェクトを想定した編集用テンプレートです。実際のコマンドとディレクトリ名が異なる場合は、リポジトリの定義に合わせて変更します。
repository/AGENTS.md
# AGENTS.md
## Repository structure
- `src/`: アプリケーションコード
- `tests/`: 自動テスト
- `docs/`: 仕様と運用ドキュメント
## Commands
- 依存関係の導入: `npm ci`
- テスト: `npm test`
- lint: `npm run lint`
- ビルド: `npm run build`
## Engineering conventions
- 新しい実装より、既存の構成と命名を優先する。
- 公開APIの挙動を変える場合は、関連ドキュメントも更新する。
## Guardrails
- 本番用の依存関係を追加する前に確認を求める。
- シークレットや認証情報をコミットしない。
## Definition of done
- 変更に関係するテスト、lint、ビルドを実行する。
- 実行できない確認項目は、理由と未確認範囲を報告する。
## Code Review Rules
- 変更範囲外の挙動が変わっていないか確認する。
- 問題を指摘する場合は、安全な修正方針も示す。Codex CLIでは/initを使って現在のディレクトリにAGENTS.mdの作成を始められます（2026年8月確認）。コマンドの導入から確認したい場合は、Codex CLIの導入と基本コマンドを参照してください。公式の現在の入口とコマンドは、OpenAI公式Codex CLIとOpenAI公式Slash commandsで確認できます。
## Code Review Rulesを実務へつなげる場合は、Codexでローカル差分・PRをレビューする手順へ進むと、実行場所との違いを整理できます。
AGENTS.mdはどこに置く？適用範囲で配置先を選ぶ
Codexはグローバル設定を確認した後、プロジェクトルートから現在の作業ディレクトリまで各階層をたどり、1階層につき最大1つの指示ファイルを採用します。
配置は「どの作業に効かせたいか」から逆算します。ディレクトリを深くするほど対象を狭められますが、現在の作業ディレクトリより下は探索対象になりません。OpenAI公式の探索範囲
個人共通の指示はCodexホームへ置く
全リポジトリで繰り返す個人の作業方針は、通常~/.codex/AGENTS.mdへ置きます。
CODEX_HOMEを設定している場合、既定の~/.codexではなく指定先がCodexホームになります（2026年8月確認）。チーム固有の規約を個人のグローバルファイルだけに置くと共有されないため、リポジトリ側へ分けます。OpenAI公式のグローバル探索規則
チーム共通はルート、局所規約は対象ディレクトリへ置く
リポジトリ全体のコマンドや完了条件はルートへ置き、特定サービスだけ異なるテストや禁止事項はそのサービスのディレクトリへ置きます。
-
HOME
~/.codex/AGENTS.md
開くリポジトリをまたいで使う個人共通の指示。
-
ROOT
repository/AGENTS.md
リポジトリ全体へ適用する構成、コマンド、完了条件。
-
DIR
repository/services/AGENTS.md
services以下だけに追加する局所的な規約。
-
OVER
repository/services/payments/AGENTS.override.md
payments階層で通常のファイルより先に選ばれる上書き指示。
Codex CloudのGitHub連携や環境設定そのものは配置ルールと分け、Codex CloudのGitHub連携と環境設定で確認してください。
CAUTION / MULTI-FOLDER
Codexデスクトップアプリの複数フォルダーを含むプロジェクトでは、公式変更履歴に自動検出の起点として「primary folder」を使う旨が記載されています（2026年8月確認）。複数フォルダーを扱う場合は、公開後もOpenAI公式Changelogで変更を確認します。
AGENTS.mdの優先順位は？探索・選択・競合を分ける
CodexのAGENTS.mdの優先順位は、探索する場所、同一階層で選ぶファイル、複数階層を結合した後の競合という3段階に分けると誤解を避けられます。
「近いファイルが常に単独で読まれる」のではありません。各階層で最大1ファイルを選んだ後、ルート側から現在の作業ディレクトリ側へ結合されます。
同一階層ではAGENTS.override.mdを先に選ぶ
プロジェクト内の各階層では、AGENTS.override.md、AGENTS.md、設定済みのfallbackファイル名の順に確認し、最初に該当する最大1ファイルを採用します。
グローバル階層でもAGENTS.override.mdがあればそちらを選び、なければAGENTS.mdを選びます。空ファイルは読み飛ばされます。OpenAI公式「How Codex discovers guidance」
複数階層ではルートからCWDへ結合する
採用されたファイルはルート側から順に結合され、現在の作業ディレクトリに近い指示ほど後ろへ入ります。
公式説明では、後から入る近い階層の指示が、競合する上位の指示を上書きします。互いに矛盾しない指示は、上位と下位の両方が残ります。
- PHASE 01 探索範囲を決める Codexホームと、プロジェクトルートからCWDまでを確認する。
- PHASE 02 各階層で1つ選ぶ override、通常、fallbackの順で最初の対象を採用する。
- PHASE 03 ルートから結合する 競合時はCWDに近い階層の指示を優先して解釈する。
現在の依頼を含む完全な優先順位は断定しない
本記事で確認したOpenAI公式AGENTS.mdドキュメントとOpenAI Cookbookでは、システム指示、開発者指示、現在の依頼、すべてのAGENTS.mdを含む一般向けの完全な優先順位表を確認できませんでした（2026年8月確認）。OpenAI公式AGENTS.mdドキュメント
OpenAI Cookbookには、AGENTS.md由来の指示が現在のユーザープロンプトより前にuser-roleのメッセージとして組み込まれる実装説明があります。ただし、その記載だけから「現在の依頼が常にAGENTS.mdへ勝つ」と一般化することは避けます。OpenAI CookbookのCodex prompting guide
CAUTION / NON-ASSERTION
本記事で確認した公式ページでは明記されていない点（2026年8月確認）：現在の依頼と永続指示が矛盾する運用を前提にしない方が安全です。今回だけ例外にする場合は、依頼文に例外の対象と理由を書き、完了後に不要なAGENTS.override.mdを残さない運用にします。
AGENTS.mdに書かない内容と代替設定
CodexのAGENTS.mdには作業手順と判断基準を書き、モデル選択、承認、サンドボックス、コマンド許可の強制設定はそれぞれの設定機構へ分けます。
自然言語の指示と、Codexが技術的に強制する設定は役割が異なります。AGENTS.mdへ「実行しないで」と書くだけで、アクセス境界や承認設定そのものが変更されるわけではありません。
セキュリティ境界をAGENTS.mdだけに任せない
ファイルやネットワークへのアクセス範囲、サンドボックス外のコマンド実行、承認条件は、対応するCodex設定やRulesで制御します。
Rulesはサンドボックス外で実行するコマンドの接頭辞を制御する仕組みで、公式には実験的機能とされています（2026年8月確認）。OpenAI公式Rulesドキュメント
プロンプト・config.toml・Rulesへ振り分ける
保存先は「繰り返すか」「リポジトリ固有か」「技術的な強制が必要か」の3点で判断します。
SCROLL → 横にスクロールできます
| 内容 | 適切な場所 | 判断の理由 | 例 |
|---|---|---|---|
| 繰り返すリポジトリ規約 | AGENTS.md | 複数タスクで継続して参照する | 変更後に実行するテスト |
| 今回だけの成果物 | 現在のプロンプト | タスク終了後に残す必要がない | 今回変更するファイルと出力形式 |
| モデル・承認・サンドボックス | config.tomlなどの設定 |
Codexの動作条件として管理する | 承認ポリシー、サンドボックスモード |
| コマンド接頭辞の許可・確認・禁止 | Rules | サンドボックス外の実行判断として適用する | gh pr viewに確認を求める |
| 長い仕様書や参考資料の全文 | 既存ドキュメント＋短い参照指示 | 重要な指示が埋もれ、容量上限へ近づく | 参照するファイル名と判断箇所だけを書く |
CAUTION / DO NOT STORE
認証情報やシークレットそのものをAGENTS.mdへ記載しません。また、AGENTS.mdだけで安全性・規約遵守・コマンド禁止が保証されるとは書かず、必要な境界は設定・Rules・承認・CIへ分けます。
AGENTS.mdが反映されないときの確認順
CodexでAGENTS.mdが反映されない場合は、作業場所、探索対象、同一階層のoverride、空ファイル、セッション、容量上限の順に確認すると原因を切り分けられます。
最初からファイルを書き直すのではなく、Codexがどのディレクトリを起点に、どのファイルを選んだかを確認します。OpenAI公式には、読み込み確認用のコマンド例も掲載されています。
6つの確認を上から進める
反映されない原因は、内容より先に配置と読み込み条件から確認します。
-
作業場所とCodexホームを確認する
codex statusで想定するworkspace rootか確認し、CODEX_HOMEが別の場所を指していないかも確認します。 -
ファイル名と内容を確認する
AGENTS.mdの大文字小文字と拡張子を確認します。空ファイルは読み飛ばされます。 -
overrideを探す
同一階層やCodexホームに
AGENTS.override.mdがあると、通常のAGENTS.mdより先に選ばれます。 - 新しい実行またはセッションで読み直す 指示チェーンは1回の実行、TUIでは通常セッション開始時に構築されます。古い場合は対象ディレクトリで再起動します。
-
fallback名の設定を確認する
独自ファイル名は
project_doc_fallback_filenamesへ正確に登録し、設定反映のため新しい実行を開始します。 -
容量上限と分割を確認する
project_doc_max_bytesへ達していないか確認し、重要な指示を短くするか、適用範囲に合わせて下位ディレクトリへ分けます。
Codexに読み込んだ指示を要約させる
公式ドキュメントでは、リポジトリルートで次のコマンドを実行し、現在の指示を要約させる確認方法が示されています。
terminal / verification
codex --ask-for-approval never "Summarize the current instructions."
codex --cd subdir --ask-for-approval never \
"Show which instruction files are active."本記事で確認したOpenAI公式AGENTS.mdドキュメントでは、指示が古い場合に手動で削除する専用キャッシュは案内されていません（2026年8月確認）。新しい実行またはTUIセッションで指示チェーンを再構築します。OpenAI公式「Verify your setup」「Troubleshoot discovery issues」
CAUTION / SIZE LIMIT
OpenAI公式AGENTS.mdページは、project_doc_max_bytesの既定値を32 KiBとし、結合した指示の追加を止める上限として説明しています（2026年8月確認）。関連する設定ページの表現は更新され得るため、本記事では32 KiBを「理想的な長さ」や「すべての環境で固定された1ファイル上限」とは断定しません。OpenAI公式Advanced Config
CodexのAGENTS.mdに関するFAQ
CodexのAGENTS.mdで本文だけでは判断しにくい点は、現在の依頼、日本語、Gitルートがない場合、OpenAI APIの4項目に整理できます。
回答のうち公式が完全な動作を明記していない内容は、断定せずに範囲を示します。
現在のプロンプトはAGENTS.mdより優先されますか？
本記事で確認したOpenAI公式ページでは現在の依頼を含む完全な優先順位表を確認できないため、「現在のプロンプトが常に優先される」とは断定できません（2026年8月確認）。OpenAI CookbookのCodex prompting guide
矛盾を前提にせず、今回だけの例外は対象と理由を依頼へ明記し、永続指示側も必要に応じて整理します。
AGENTS.mdは日本語で書けますか？
AGENTS.mdはMarkdownのテキストファイルなので日本語を記載できますが、本記事で確認したOpenAI公式AGENTS.mdドキュメントでは日本語指示の完全な挙動差や推奨言語を確認できませんでした（2026年8月確認）。OpenAI公式AGENTS.mdドキュメント
チームが誤読しない言語を選び、コマンド、ファイル名、設定名は実際の表記をそのまま書きます。
Gitルートが見つからない場合はどこを探索しますか？
Codexがプロジェクトルートを見つけられない場合は、現在の作業ディレクトリだけでAGENTS.mdなどの指示ファイルを確認します。
OpenAI公式AGENTS.mdドキュメントに記載された条件であり、通常のGitルートからCWDまでの探索とは範囲が異なります（2026年8月確認）。OpenAI公式のプロジェクト探索規則
OpenAI APIもAGENTS.mdを自動で読みますか？
本記事で確認したOpenAI公式AGENTS.mdドキュメントでは、OpenAI APIが任意のリポジトリにあるAGENTS.mdを自動探索するとは案内されていません（2026年8月確認）。OpenAI公式AGENTS.mdドキュメント
APIで同様の指示を使う場合は、アプリ側がどのファイルを読み、どのメッセージとして渡すかを別途設計する必要があると考えられます。
まとめ｜AGENTS.mdはルート1枚から始める
CodexのAGENTS.mdは、ルートに短い1枚を置き、範囲の違う指示だけを下位ディレクトリへ分けると、適用先と競合を管理しやすくなります。
探索場所、同一階層でのファイル選択、ルートからCWDへの結合を分けて考えれば、優先順位の混同を避けられます。モデルやアクセス境界の設定はAGENTS.mdへ集約せず、対応する設定へ分けます。
次に行うこと：リポジトリルートへAGENTS.mdを1つ作り、実在するテスト・lint・ビルドのコマンドと、変更後の完了条件から書き始めてください。
OpenAI公式の引用元一覧
本記事の事実確認には、OpenAI公式のAGENTS.md、設定、Rules、CLI、変更履歴など12ページを使用し、2026年8月4日に最終確認しました。
本文で使用した主張と対応する公式ページを、用途が分かる形で一覧化します。
- OpenAI公式｜Custom instructions with AGENTS.md
- OpenAI公式｜Glossary
- OpenAI公式｜Codex best practices
- OpenAI公式｜Customization overview
- OpenAI公式｜Config Basics
- OpenAI公式｜Advanced Config
- OpenAI公式｜Configuration reference
- OpenAI公式｜Rules
- OpenAI公式｜Codex CLI
- OpenAI公式｜Slash commands
- OpenAI公式｜Changelog
- OpenAI Cookbook｜Codex prompting guide
あわせて読みたいCodex関連記事
CodexのAGENTS.mdを整えた後は、総合ガイドで利用環境を選び、CLI・Cloud・コードレビュー・IDE拡張機能から必要な手順だけ確認できます。
最も読んでほしい総合ガイドを先頭に、次の作業へ進む順で並べています。
コメント